{
  "openapi": "3.1.0",
  "info": {
    "title": "SoundSync Public API",
    "version": "2026-11-17",
    "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."
      },
      "CustomerAccountQueryToken": {
        "type": "apiKey",
        "in": "query",
        "name": "token",
        "description": "Private customer-account session accepted by the documented delivery fallback. Not a legacy library token. Prefer Authorization: Bearer to avoid credentials in URLs."
      },
      "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."
      },
      "NoticeToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Independent notice-only capability. Not a customer account session, product credential or offline license grant."
      },
      "FastSpringSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "X-FS-Signature",
        "description": "HMAC-SHA256 of exact raw bytes with the connection webhook secret; generated by FastSpring."
      },
      "FastSpringFulfillment": {
        "type": "http",
        "scheme": "basic",
        "description": "Private connection-specific fulfillment credential; never distribute in a plugin."
      },
      "WooCommerceSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "X-WC-Webhook-Signature",
        "description": "Raw-byte HMAC-SHA256 plus matching source origin. Registration pings are not fulfillment."
      }
    },
    "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/2fa/disable": {
      "post": {
        "summary": "POST /api/account/2fa/disable. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path.",
        "description": "Active compatibility alias of POST /api/account/2fa/disable. The same handler is used after the stricter root-path shared-session check. An alias is not a dry run or a fresh idempotency boundary. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/accounts"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "Shared SoundSync account session only at this older root path; store-only sessions return 403 STOREFRONT_SESSION_SCOPE before the canonical handler.",
        "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-error-codes": [
          "STOREFRONT_SESSION_SCOPE"
        ],
        "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/2fa/enable": {
      "post": {
        "summary": "POST /api/account/2fa/enable. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path.",
        "description": "Active compatibility alias of POST /api/account/2fa/enable. The same handler is used after the stricter root-path shared-session check. An alias is not a dry run or a fresh idempotency boundary. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path. 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/api/accounts"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "Shared SoundSync account session only at this older root path; store-only sessions return 403 STOREFRONT_SESSION_SCOPE before the canonical handler.",
        "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-error-codes": [
          "STOREFRONT_SESSION_SCOPE"
        ],
        "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/2fa/setup": {
      "post": {
        "summary": "POST /api/account/2fa/setup. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path.",
        "description": "Active compatibility alias of POST /api/account/2fa/setup. The same handler is used after the stricter root-path shared-session check. An alias is not a dry run or a fresh idempotency boundary. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/accounts"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "Shared SoundSync account session only at this older root path; store-only sessions return 403 STOREFRONT_SESSION_SCOPE before the canonical handler.",
        "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-error-codes": [
          "STOREFRONT_SESSION_SCOPE"
        ],
        "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/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 session token",
        "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 session token",
        "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 session token",
        "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": "Private email-change token authorizes viewing its confirmation form only; GET does not consume the token or change the address.",
        "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": "Private email-change confirmation token; POST confirms the pending change without requiring a sign-in session.",
        "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/payment-method": {
      "get": {
        "summary": "Read the signed-in shared account's saved-card preview",
        "description": "Historical first-party saved-card endpoint for the signed-in shared SoundSync account, not the selected developer workspace. Uses the configured legacy Stripe client; there is no request environment selector. Store-only sessions are denied with 403 STOREFRONT_SESSION_SCOPE before Stripe or card queries. This does not create a checkout, tax quote, payout destination, Connect onboarding, transfer or automatic-execution change. Prefer the current developer Billing API for workspace billing and managed checkout for customer purchases. No saved method returns 404 No payment method found, not a 200 empty card. Returns only brand, last4, exp_month and exp_year when available, never the full card number or security code. This read contacts Stripe but does not attach a card.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/accounts"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: brand, last4, exp_month, exp_year.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "brand": {
                      "type": "string"
                    },
                    "last4": {
                      "type": "string"
                    },
                    "exp_month": {
                      "type": "integer"
                    },
                    "exp_year": {
                      "type": "integer"
                    }
                  },
                  "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 session token",
        "x-access-scope": "Shared SoundSync account session; reads only that account user's stored card preview, not a selected workspace or store-only profile.",
        "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": [
          "STOREFRONT_SESSION_SCOPE"
        ],
        "x-source-files": [
          "routes/accountRoutes.js",
          "controllers/accountController.js",
          "middleware/authMiddleware.js",
          "services/storefrontCustomerCredentialService.js",
          "lib/stripe.js"
        ]
      },
      "post": {
        "summary": "Save the signed-in shared account's legacy Stripe payment method",
        "description": "Historical first-party saved-card endpoint for the signed-in shared SoundSync account, not the selected developer workspace. Uses the configured legacy Stripe client; there is no request environment selector. Store-only sessions are denied with 403 STOREFRONT_SESSION_SCOPE before Stripe or card queries. This does not create a checkout, tax quote, payout destination, Connect onboarding, transfer or automatic-execution change. Prefer the current developer Billing API for workspace billing and managed checkout for customer purchases. Requires a Stripe payment-method identifier, not raw card data. Can create a Stripe customer and save its ID, attach the supplied method, set the default invoice method and persist its identifier. These provider/database writes are not one atomic transaction. On an uncertain failure, inspect the saved method before retrying. A successful save does not itself collect a charge or pay a payout.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/accounts"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: message, brand, last4, exp_month, exp_year.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "brand": {
                      "type": "string"
                    },
                    "last4": {
                      "type": "string"
                    },
                    "exp_month": {
                      "type": "integer"
                    },
                    "exp_year": {
                      "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 session token",
        "x-access-scope": "Shared SoundSync account session; changes only the signed-in account user's legacy Stripe customer/default payment method.",
        "x-request-fields": [
          "payment_method_id: 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": [
          "STOREFRONT_SESSION_SCOPE"
        ],
        "x-source-files": [
          "routes/accountRoutes.js",
          "controllers/accountController.js",
          "middleware/authMiddleware.js",
          "services/storefrontCustomerCredentialService.js",
          "lib/stripe.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "payment_method_id": {
                    "type": "string"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "payment_method_id"
                ]
              }
            }
          }
        }
      }
    },
    "/api/account/profile": {
      "put": {
        "summary": "Update profile details or request an email change",
        "description": "Names can be cleared independently. Customer email edits apply immediately to the permitted profile and are not proof of inbox verification. A store-only session updates only that store contact/credential; an email change invalidates old store sessions. Marketing contacts, supported unsent work and current contact references follow the permitted edit. A shared customer session changes the shared customer profile without overwriting saved store overrides; store edits never retarget the shared Stripe billing identity. Platform/developer email changes use the pending verified email-change flow. Issued invoices and sent messages are not rewritten; saved marketing suppressions remain in force.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/accounts"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: message, emailChanged, emailChangeRequested, signInRequired, emailDelivery, user.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "emailChanged": {
                      "type": "boolean"
                    },
                    "emailChangeRequested": {
                      "type": "boolean"
                    },
                    "signInRequired": {
                      "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 session token",
        "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": "Shared-account responses retain the saved customer, developer, owner, admin, support or reseller role; legacy rows without a role use the existing admin/reseller fallback. This identity label does not grant workspace permissions. A store-only session returns user.storefrontSession:true, its store identifiers, security.storefrontOnly:true and sharedAccountSettingsAvailable:false instead of shared two-factor or session counts. Use shared sign-in for global security settings. A failed session-count query returns 500 Failed to load security settings instead of presenting a fabricated zero. Treat the count as unavailable on failure; a successful response reports the saved-session count, not proof that every session is currently online.",
        "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",
                          "description": "The saved personal account role, not a workspace membership role or authorization grant."
                        },
                        "storefrontSession": {
                          "type": "boolean"
                        },
                        "storefrontDeveloperId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "storefrontCustomerId": {
                          "type": "integer",
                          "minimum": 1
                        }
                      },
                      "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"
                          ]
                        },
                        "storefrontOnly": {
                          "type": "boolean"
                        },
                        "sharedAccountSettingsAvailable": {
                          "type": "boolean"
                        }
                      },
                      "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 session token",
        "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",
          "services/storefrontCustomerCredentialService.js"
        ]
      }
    },
    "/api/account/update-password": {
      "post": {
        "summary": "Change the password using the current password",
        "description": "Send currentPassword (or oldPassword) and newPassword. A store-only session changes only its store password and returns signInRequired:true; sign in again to that store. Shared SoundSync passwords and other stores are untouched. Shared-account verification, replacement and other-session revocation remain transactional: a failed revocation rolls the change back, and the recognized current token is retained where present. Passwords must use at least 8 characters and fit within 72 UTF-8 bytes.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/accounts"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: message, code, signInRequired.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "signInRequired": {
                      "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 session token",
        "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. Send storefrontSlug for store-local recovery: a saved store credential receives a store-only reset. A separately TXT-verified external website uses its saved reset callback, not an arbitrary supplied reset destination. Without store context, shared-account recovery remains separate. Invitation recovery requires account_type and retains its platform destination. 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. Send storefrontSlug for a saved store-local credential and keep it through any two-factor continuation. The returned store-only token cannot authorize another store or global security settings. Product-scoped customer-token activation checks that the developer matches and still requires ownership/device proof. Generated native packages retain their documented shared-customer login flow. Omit storefront context and use the original shared credentials for shared SoundSync login. Existing two-factor and inbox verification requirements remain. Marketing choice compatibility fields do not require a new opt-in checkbox. For team invitation sign-in, use the developer/platform login context. accountType and its account_type alias select the login-record family, not the role granted after authentication. Separate customer and developer records may share an email. Complete existing password/2FA checks and invitation acceptance; a matching email alone grants no workspace membership.",
        "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"
                    },
                    "session": {
                      "type": "object",
                      "properties": {
                        "expiresAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "expiresInSeconds": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "refreshSupported": {
                          "const": false
                        }
                      },
                      "additionalProperties": true
                    },
                    "user": {
                      "type": "object",
                      "properties": {
                        "storefrontSession": {
                          "type": "boolean"
                        },
                        "storefrontDeveloperId": {
                          "type": "integer",
                          "minimum": 1
                        }
                      },
                      "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",
          "storefrontSlug: string",
          "marketingOptIn: boolean",
          "marketingOptOut: boolean",
          "accountType: customer | developer | reseller | owner | admin | support | platform. Login-record selection hint only, not an asserted role or permission. platform selects a non-customer account when a separate customer account shares the email."
        ],
        "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/storefrontCustomerCredentialService.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"
                  },
                  "storefrontSlug": {
                    "type": "string"
                  },
                  "marketingOptIn": {
                    "type": "boolean"
                  },
                  "marketingOptOut": {
                    "type": "boolean"
                  },
                  "accountType": {
                    "type": "string",
                    "enum": [
                      "customer",
                      "developer",
                      "reseller",
                      "owner",
                      "admin",
                      "support",
                      "platform"
                    ],
                    "description": "Login-record selection hint only, not an asserted role or permission. platform selects a non-customer account when a separate customer account shares the email."
                  }
                },
                "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 session token",
        "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 signed-in user. With developerWorkspace=1, also returns the current permitted workspace context without creating a workspace, membership or session. An active context has access; an eligible new developer can instead have available:true, initializationRequired:true and no access until the existing authenticated setup initializes their own workspace. Missing/inactive membership or workspace returns HTTP 200 with available:false and reason; it is not an expired-login response. A platform owner can have ownerPortalAvailable:true but no developer workspace. A customer-role account with active team membership can have permitted developer access. Identity alone, a selector or cached context never authorizes another route: the server rechecks current permissions and product scope. Responses use Cache-Control:no-store. Unexpected context failures, including invalid selector parsing, currently return 500 Failed to load session; do not treat every failed context check as invalid credentials.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/accounts"
        },
        "parameters": [
          {
            "name": "developerWorkspace",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "required": false,
            "description": "Only the exact value 1 includes developerWorkspace; omitted or other values return account identity only."
          },
          {
            "name": "x-soundsync-workspace-id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]*$"
            },
            "description": "Optional workspace selection for developerWorkspace=1. Active membership is still required. x-developer-workspace-id is a supported header alias."
          },
          {
            "name": "workspaceId",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "required": false,
            "description": "Optional selector when requesting workspace context. workspace_id is an accepted alias; the workspace header takes precedence."
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: user, developerWorkspace.",
            "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"
                          ]
                        },
                        "is_admin": {
                          "type": "boolean"
                        }
                      },
                      "additionalProperties": true
                    },
                    "developerWorkspace": {
                      "oneOf": [
                        {
                          "type": "object",
                          "properties": {
                            "available": {
                              "const": true
                            },
                            "initializationRequired": {
                              "const": false
                            },
                            "ownerPortalAvailable": {
                              "type": "boolean"
                            },
                            "access": {
                              "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
                            }
                          },
                          "required": [
                            "available",
                            "initializationRequired",
                            "ownerPortalAvailable",
                            "access"
                          ],
                          "additionalProperties": true
                        },
                        {
                          "type": "object",
                          "properties": {
                            "available": {
                              "const": true
                            },
                            "initializationRequired": {
                              "const": true
                            },
                            "ownerPortalAvailable": {
                              "type": "boolean"
                            },
                            "reason": {
                              "type": "null"
                            }
                          },
                          "required": [
                            "available",
                            "initializationRequired",
                            "ownerPortalAvailable",
                            "reason"
                          ],
                          "additionalProperties": true
                        },
                        {
                          "type": "object",
                          "properties": {
                            "available": {
                              "const": false
                            },
                            "initializationRequired": {
                              "const": false
                            },
                            "ownerPortalAvailable": {
                              "type": "boolean"
                            },
                            "reason": {
                              "type": "string",
                              "enum": [
                                "developer_workspace_access_required",
                                "developer_workspace_not_found",
                                "developer_team_membership_inactive"
                              ]
                            }
                          },
                          "required": [
                            "available",
                            "initializationRequired",
                            "ownerPortalAvailable",
                            "reason"
                          ],
                          "additionalProperties": true
                        }
                      ],
                      "description": "Optional read-only workspace discovery. available:true with initializationRequired:true is not an initialized workspace or a permission grant."
                    }
                  },
                  "required": [
                    "user"
                  ],
                  "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 session token",
        "x-access-scope": "The signed-in account. Optional workspace discovery requires its current permitted membership or eligible initial setup; every workspace action rechecks its own authorization.",
        "x-request-fields": [
          "query developerWorkspace: string. Only the exact value 1 includes developerWorkspace; omitted or other values return account identity only.",
          "header x-soundsync-workspace-id: string. Optional workspace selection for developerWorkspace=1. Active membership is still required. x-developer-workspace-id is a supported header alias.",
          "query workspaceId: integer. Optional selector when requesting workspace context. workspace_id is an accepted alias; the workspace header takes precedence."
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.",
        "security": [
          {
            "AccountSession": []
          }
        ],
        "x-contract-coverage": "Reviewed field schemas; inspect 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",
          "services/developerTeamService.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 with email verification or a verified popup setup proof",
        "description": "Ordinary registration returns 202 and creates an unverified account. A valid popupClaimToken creates a verified customer account and returns 200 ACCOUNT_READY without sending a second verification email. The proof must be unexpired, unconsumed and bound to the same email and required storefrontSlug; existing accounts return 409 and should sign in. Neither response creates 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. A valid teamInviteToken preserves the private developer invitation through developer signup and verification; it is not customer membership or acceptance of the invitation.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/accounts"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "ACCOUNT_READY: customer account created using a valid verified popup setup proof. The reward was already awarded. Sign in separately; no session is created.",
            "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
                }
              }
            }
          },
          "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",
          "popupClaimToken: string. Private verified popup proof for customer account setup after the reward is awarded. Requires the same email and storefrontSlug. Never log or persist this token in browser storage.",
          "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",
          "teamInviteToken: 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",
          "services/developerTeamService.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"
                  },
                  "popupClaimToken": {
                    "type": "string",
                    "description": "Private verified popup proof for customer account setup after the reward is awarded. Requires the same email and storefrontSlug. Never log or persist this token in browser storage."
                  },
                  "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"
                  },
                  "teamInviteToken": {
                    "type": "string"
                  }
                },
                "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"
                  },
                  "popupClaimToken": {
                    "type": "string",
                    "description": "Private verified popup proof for customer account setup after the reward is awarded. Requires the same email and storefrontSlug. Never log or persist this token in browser storage."
                  },
                  "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"
                  },
                  "teamInviteToken": {
                    "type": "string"
                  }
                },
                "required": [
                  "email",
                  "password"
                ],
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/auth/reseller-verification": {
      "post": {
        "summary": "Request verification mail for a private pending reseller invitation",
        "description": "Generic success does not confirm account existence, invitation acceptance or email delivery. Keep invitation tokens private; repeated requests remain rate/cooldown limited.",
        "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
                }
              }
            }
          },
          "400": {
            "description": "Invalid input 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 intended-recipient invitation proof, active pending invitation/account and resend limits.",
        "x-request-fields": [
          "email: string (required)",
          "partnerInviteToken: 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",
          "services/partnerProgramVerificationMailService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "partnerInviteToken": {
                    "type": "string"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "email",
                  "partnerInviteToken"
                ]
              }
            }
          }
        }
      }
    },
    "/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 store reset changes only that store password and invalidates its credential sessions; shared SoundSync credentials and other stores remain unchanged. Shared-account recovery retains its account-session revocation behavior. 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 session token",
        "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/team-invitation/preview": {
      "post": {
        "summary": "Inspect a private team invitation before developer signup or login",
        "description": "Public transport with private token authority. The response contains the invited email: do not publish tokens, log the response or cache it. Invalid, expired, canceled or unavailable invitations fail closed. Rate-limited.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/team-accounts"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: invitation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "invitation": {
                      "type": "object",
                      "properties": {
                        "email": {
                          "type": "string"
                        },
                        "role": {
                          "type": "string"
                        },
                        "workspaceName": {
                          "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"
                }
              }
            }
          },
          "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"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific 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": "Valid private invitation token; no customer session substitutes for developer membership.",
        "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/authRoutes.js",
          "controllers/authController.js",
          "services/developerTeamService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "token"
                ]
              }
            }
          }
        }
      }
    },
    "/api/auth/team-invitation/verification": {
      "post": {
        "summary": "Resend developer verification and return to the team invitation",
        "description": "The response is deliberately non-enumerating. Uses the developer login, even if a separate customer account shares the email. It does not accept membership or log the user in.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/team-accounts"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: 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"
                }
              }
            }
          },
          "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"
                }
              }
            }
          },
          "429": {
            "description": "Request or operation limit reached; do not create duplicate financial work.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific 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 supplied email must match the private invitation.",
        "x-request-fields": [
          "teamInviteToken: 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": [],
        "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/developerTeamService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "teamInviteToken": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "teamInviteToken",
                  "email"
                ]
              }
            }
          }
        }
      }
    },
    "/api/auth/verify-email": {
      "get": {
        "summary": "Consume an account verification link and display HTML",
        "description": "Consumes a private one-use verification token. GET and ordinary POST requests return HTML. POST with Accept:application/json returns verified:true, signInRequired:true and the supported loginUrl; missing/expired/used tokens return 400 INVALID_VERIFICATION_TOKEN JSON and unexpected failure returns 500 VERIFICATION_FAILED JSON. Successful verification does not create a signed-in session. A separately TXT-verified external website can receive the email at its saved callback; arbitrary supplied return destinations are not accepted. Never poll, log or share a verification URL.",
        "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 with HTML or requested JSON response",
        "description": "Consumes a private one-use verification token. GET and ordinary POST requests return HTML. POST with Accept:application/json returns verified:true, signInRequired:true and the supported loginUrl; missing/expired/used tokens return 400 INVALID_VERIFICATION_TOKEN JSON and unexpected failure returns 500 VERIFICATION_FAILED JSON. Successful verification does not create a signed-in session. A separately TXT-verified external website can receive the email at its saved callback; arbitrary supplied return destinations are not accepted. Never poll, log or share a verification URL.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/accounts"
        },
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Send application/json for the server-to-server verification response; otherwise HTML is returned."
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: text/html.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verified": {
                      "const": true
                    },
                    "signInRequired": {
                      "const": true
                    },
                    "loginUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "verified",
                    "signInRequired",
                    "loginUrl"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "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": [
          "header Accept: string. Send application/json for the server-to-server verification response; otherwise HTML is returned.",
          "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/claim": {
      "post": {
        "summary": "POST /api/checkout/claim",
        "description": "",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/evaluation"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful idempotent replay or duplicate confirmation; inspect the linked operation contract.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "claimed": {
                      "type": "boolean"
                    },
                    "freeClaim": {
                      "type": "boolean"
                    },
                    "checkoutBypassed": {
                      "type": "boolean"
                    },
                    "alreadyClaimed": {
                      "type": "boolean"
                    },
                    "orderId": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "productId": {
                      "type": "integer",
                      "minimum": 1
                    }
                  },
                  "required": [
                    "claimed",
                    "freeClaim",
                    "checkoutBypassed"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "201": {
            "description": "HTTP 201: claimed, freeClaim, checkoutBypassed, alreadyClaimed, orderId, productId.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "claimed": {
                      "type": "boolean"
                    },
                    "freeClaim": {
                      "type": "boolean"
                    },
                    "checkoutBypassed": {
                      "type": "boolean"
                    },
                    "alreadyClaimed": {
                      "type": "boolean"
                    },
                    "orderId": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "productId": {
                      "type": "integer",
                      "minimum": 1
                    }
                  },
                  "required": [
                    "claimed",
                    "freeClaim",
                    "checkoutBypassed"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/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"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "Verified customer account; fixed verified website/storefront scope. Full Store must be activated for production. Server price must be zero; positive prices never create a provider checkout.",
        "x-request-fields": [
          "productId: integer (required)",
          "storefrontSlug: string",
          "headlessOrigin: string. Exact HTTPS origin verified for storefrontSlug in External website settings; saved callback paths are used.",
          "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/productCheckoutRoutes.js",
          "services/stripeProductCheckoutService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "productId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "storefrontSlug": {
                    "type": "string"
                  },
                  "headlessOrigin": {
                    "type": "string",
                    "format": "uri",
                    "description": "Exact HTTPS origin verified for storefrontSlug in External website settings; saved callback paths are used."
                  },
                  "marketingOptIn": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "productId"
                ],
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/checkout/external": {
      "post": {
        "summary": "Open the saved provider checkout URL",
        "description": "External licensing, not Full Store. externalEnvironment defaults to live and is independent of Stripe/PayPal environment. Opens only the saved allowed URL. It never calculates SoundSync tax, captures/confirms payment or grants a license. A provider return URL is not SoundSync checkout-status confirmation.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/custom-websites"
        },
        "parameters": [],
        "responses": {
          "201": {
            "description": "201: Inspect the response schema and conditional states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "provider": {
                      "type": "string"
                    },
                    "paymentFlow": {
                      "const": "external"
                    },
                    "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 session token",
        "x-access-scope": "Verified customer session and independently verified website; one active allowed product/provider/environment mapping.",
        "x-request-fields": [
          "provider: fastspring | gumroad | woocommerce (required)",
          "productId: integer (required)",
          "storefrontSlug: string (required)",
          "headlessOrigin: string (required)",
          "externalEnvironment: 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-source-files": [
          "routes/productCheckoutRoutes.js",
          "services/commerceIntegrationService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "provider": {
                    "type": "string",
                    "enum": [
                      "fastspring",
                      "gumroad",
                      "woocommerce"
                    ]
                  },
                  "productId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "storefrontSlug": {
                    "type": "string"
                  },
                  "headlessOrigin": {
                    "type": "string"
                  },
                  "externalEnvironment": {
                    "type": "string",
                    "enum": [
                      "test",
                      "live"
                    ]
                  }
                },
                "additionalProperties": true,
                "required": [
                  "provider",
                  "productId",
                  "storefrontSlug",
                  "headlessOrigin"
                ]
              }
            }
          }
        }
      }
    },
    "/api/checkout/location-evidence": {
      "get": {
        "summary": "Obtain a short-lived buyer-browser location proof",
        "description": "Fetch directly from the buyer browser using credentials:omit and Origin matching headlessOrigin. Discover the separate public issuer via payment-methods.locationEvidenceOrigin; do not assume the API origin serves the edge adapter. The five-minute proof binds observed country and visitor-IP hash. Forward as locationEvidenceToken through your private website backend with genuine visitor-IP context. A website key cannot sign this proof. Missing configured edge support returns 503; do not bypass tax evidence checks.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/custom-websites"
        },
        "parameters": [
          {
            "name": "headlessOrigin",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "storefrontSlug",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200: Inspect the response schema and conditional states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "evidence": {
                      "type": "string"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "evidence",
                    "expiresAt"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input 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": "Origin/storefront-bound edge-observed location proof, not account authorization.",
        "x-request-fields": [
          "query headlessOrigin: string (required)",
          "query storefrontSlug: 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": [
          "cloudflare/tax-evidence-proxy.mjs",
          "routes/productCheckoutRoutes.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/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
                    },
                    "runtime": {
                      "type": "object",
                      "properties": {
                        "environment": {
                          "enum": [
                            "test",
                            "live"
                          ]
                        },
                        "evaluation": {
                          "type": "boolean"
                        },
                        "developerBillingEnabled": {
                          "type": "boolean"
                        },
                        "evaluationOrigin": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "uri"
                        }
                      },
                      "additionalProperties": true
                    },
                    "customerSession": {
                      "type": "object",
                      "properties": {
                        "tokenLifetimeSeconds": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "refreshSupported": {
                          "const": false
                        },
                        "websiteSessionDefaultSeconds": {
                          "type": "integer",
                          "minimum": 0
                        }
                      },
                      "additionalProperties": true
                    },
                    "locationEvidenceOrigin": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "uri",
                      "description": "Public buyer-browser proof issuer; may differ from the API origin."
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "methods"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific 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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/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. Configured products use the selected offerId with offerVersionId and priceVersionId from the current catalog. Stale terms require reloading and customer review, not silent substitution. A recurring offer checks out alone with quantity one. One-time carts use one developer and currency. Qualifying coupon and automatic/BOGO promotions enforce the post-discount cart minimum before tax, not a separate minimum on every discounted line; fully free carts require explicit supported free-redemption permission. Custom websites use the verified exact origin, stored callbacks and private website context. Quote/product requests must agree on customer, cart, location and fresh quote. Never substitute server geolocation or treat a browser return as confirmed payment. 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 session token",
        "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",
          "quoteId: string",
          "locationEvidenceToken: string. Short-lived browser-edge location proof, not a customer token.",
          "headlessOrigin: string",
          "storefrontSlug: string",
          "paymentProvider: stripe | paypal",
          "marketingOptIn: boolean",
          "marketingOptOut: boolean",
          "offerId: string",
          "offerVersionId: string",
          "priceVersionId: 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": [
          "CHOOSE_OFFER_REQUIRED",
          "OFFER_CHANGED",
          "CHECKOUT_OFFER_REQUIRED",
          "CHECKOUT_OFFER_VERSION_CONFLICT",
          "SUBSCRIPTION_CART_UNSUPPORTED"
        ],
        "x-source-files": [
          "routes/productCheckoutRoutes.js",
          "services/checkoutOfferItems.js",
          "services/checkoutOfferService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "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",
                    "items": {
                      "type": "object",
                      "properties": {
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "quantity": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 100
                        },
                        "offerId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "offerVersionId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "priceVersionId": {
                          "type": "string",
                          "format": "uuid"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "productId"
                      ]
                    },
                    "maxItems": 100
                  },
                  "promoCode": {
                    "type": "string"
                  },
                  "taxQuoteId": {
                    "type": "string"
                  },
                  "quoteId": {
                    "type": "string"
                  },
                  "locationEvidenceToken": {
                    "type": "string",
                    "maxLength": 2048,
                    "description": "Short-lived browser-edge location proof, not a customer token."
                  },
                  "headlessOrigin": {
                    "type": "string",
                    "format": "uri"
                  },
                  "storefrontSlug": {
                    "type": "string"
                  },
                  "paymentProvider": {
                    "enum": [
                      "stripe",
                      "paypal"
                    ]
                  },
                  "marketingOptIn": {
                    "type": "boolean"
                  },
                  "marketingOptOut": {
                    "type": "boolean"
                  },
                  "offerId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "offerVersionId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "priceVersionId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "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. Configured products use the selected offerId with offerVersionId and priceVersionId from the current catalog. Stale terms require reloading and customer review, not silent substitution. A recurring offer checks out alone with quantity one. One-time carts use one developer and currency. Qualifying coupon and automatic/BOGO promotions enforce the post-discount cart minimum before tax, not a separate minimum on every discounted line; fully free carts require explicit supported free-redemption permission. Custom websites use the verified exact origin, stored callbacks and private website context. Quote/product requests must agree on customer, cart, location and fresh quote. Never substitute server geolocation or treat a browser return as confirmed payment. 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 session token",
        "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",
          "headlessOrigin: string",
          "storefrontSlug: string",
          "locationEvidenceToken: string. Short-lived browser-edge location proof, not a customer token.",
          "offerId: string",
          "offerVersionId: string",
          "priceVersionId: string",
          "quoteId: 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": [
          "CHOOSE_OFFER_REQUIRED",
          "OFFER_CHANGED",
          "CHECKOUT_OFFER_REQUIRED",
          "CHECKOUT_OFFER_VERSION_CONFLICT",
          "SUBSCRIPTION_CART_UNSUPPORTED"
        ],
        "x-source-files": [
          "routes/productCheckoutRoutes.js",
          "services/checkoutQuoteService.js",
          "services/checkoutOfferItems.js",
          "services/checkoutOfferService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "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
                        },
                        "offerId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "offerVersionId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "priceVersionId": {
                          "type": "string",
                          "format": "uuid"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "productId"
                      ]
                    },
                    "maxItems": 100
                  },
                  "countryCode": {
                    "type": "string"
                  },
                  "regionCode": {
                    "type": "string"
                  },
                  "postalCode": {
                    "type": "string"
                  },
                  "promoCode": {
                    "type": "string"
                  },
                  "headlessOrigin": {
                    "type": "string",
                    "format": "uri"
                  },
                  "storefrontSlug": {
                    "type": "string"
                  },
                  "locationEvidenceToken": {
                    "type": "string",
                    "maxLength": 2048,
                    "description": "Short-lived browser-edge location proof, not a customer token."
                  },
                  "offerId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "offerVersionId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "priceVersionId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "quoteId": {
                    "type": "string"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/checkout/status": {
      "get": {
        "summary": "Read confirmed checkout state for the purchasing customer",
        "description": "Read-only: never captures payment, creates access or pays earnings. A success URL is not payment proof. Current library entitlements determine access after a refund or revocation.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/custom-websites"
        },
        "parameters": [
          {
            "name": "sessionId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "storefrontSlug",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200: Inspect the response schema and conditional states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "fulfilled": {
                      "type": "boolean"
                    },
                    "provider": {
                      "type": "string",
                      "enum": [
                        "stripe",
                        "paypal"
                      ]
                    },
                    "currency": {
                      "type": "string"
                    },
                    "totalCents": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "taxAmountCents": {
                      "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"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "Verified purchasing customer, matching storefront and backend payment environment.",
        "x-request-fields": [
          "query sessionId: string (required)",
          "query storefrontSlug: 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-request-body": "No body fields are read by this operation.",
        "x-source-files": [
          "routes/productCheckoutRoutes.js",
          "services/headlessCheckoutStatusService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/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": "/api/developer/dashboard/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 session token",
        "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": "/api/developer/dashboard/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 session token",
        "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": "/api/developer/dashboard/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 America/New_York 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 session token",
        "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": "/api/developer/dashboard/launch-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: 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 session token",
        "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. Requires a current customer-account session, either shared SoundSync sign-in or an authorized store-scoped customer session. A bare legacy serial/download proof returns 403 CUSTOMER_ACCOUNT_REQUIRED. The query names token, download_token and libraryToken are transport aliases where documented, not permission to substitute a different token type. Prefer Authorization: Bearer to keep credentials out of URLs. 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. SoundSync-wide customer suspension returns 403 CUSTOMER_ACCOUNT_RESTRICTED, including for an existing shared account session; store closure remains store-scoped. Shared library tokens follow their own token/ownership checks and do not replace required customer-account sign-in. 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": "Account Bearer session token",
        "x-access-scope": "Current customer-account session and verified customer ownership. Store-scoped sessions remain confined to their storefront; a legacy serial/download token is not account sign-in.",
        "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": [
          {
            "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-error-codes": [
          "SESSION_VERIFICATION_UNAVAILABLE",
          "LIBRARY_SESSION_REVOKED",
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "CUSTOMER_STORE_CLOSED",
          "CUSTOMER_ACCOUNT_REQUIRED"
        ],
        "x-source-files": [
          "routes/deliveryRoutes.js",
          "controllers/deliveryController.js",
          "services/customerLibraryIdentityService.js"
        ]
      }
    },
    "/api/delivery/products/{productId}/versions/{versionId}/files/{fileIndex}": {
      "get": {
        "summary": "Deliver a current or retained product-version file",
        "description": "Requires a signed-in customer-account session: use Authorization: Bearer, or the supported private token query fallback. A legacy library/download token alone returns CUSTOMER_ACCOUNT_REQUIRED. Valid store-scoped sessions are limited to their own store; shared-account sessions retain their permitted store/product checks. Never publish token-bearing URLs. versionId accepts retained numeric/UUID versions and supported current/current-version identifiers. Software version does not create another paid ownership tier. application/json returns a private link; the default redirects with 302. Already issued links expire independently of later restrictions.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/protected-content"
        },
        "parameters": [
          {
            "name": "productId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "versionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fileIndex",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "token",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Private customer-account session fallback. Prefer the Authorization header to avoid credentials in URLs."
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: url, filename, expiresIn.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "filename": {
                      "type": "string"
                    },
                    "expiresIn": {
                      "type": "integer",
                      "minimum": 0
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "302": {
            "description": "Redirect to a newly authorized private file URL.",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                },
                "description": "Private signed storage URL; do not publish."
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token OR private customer-account token query fallback (prefer Bearer)",
        "x-access-scope": "Signed-in customer-account identity and current product/store access. File index is zero-based.",
        "x-request-fields": [
          "query token: string. Private customer-account session fallback. Prefer the Authorization header to avoid credentials in URLs."
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.",
        "security": [
          {
            "AccountSession": []
          },
          {
            "CustomerAccountQueryToken": []
          }
        ],
        "x-contract-coverage": "Reviewed 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": [
          "CUSTOMER_ACCOUNT_REQUIRED",
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "CUSTOMER_STORE_CLOSED",
          "LIBRARY_SESSION_REVOKED",
          "SESSION_VERIFICATION_UNAVAILABLE"
        ],
        "x-source-files": [
          "routes/deliveryRoutes.js",
          "controllers/deliveryController.js",
          "services/protectedContentCatalogService.js",
          "services/purchaseOfferLibraryService.js",
          "services/customerLibraryIdentityService.js",
          "services/customerStoreAccessService.js"
        ]
      }
    },
    "/api/delivery/protected-content": {
      "get": {
        "summary": "List compatible protected releases for an instrument",
        "description": "Requires a signed-in customer-account session: use Authorization: Bearer, or the supported private token query fallback. A legacy library/download token alone returns CUSTOMER_ACCOUNT_REQUIRED. Valid store-scoped sessions are limited to their own store; shared-account sessions retain their permitted store/product checks. Never publish token-bearing URLs. host_version is a software compatibility value, not a purchased-major restriction. A catalog entry or download URL does not authorize playback; verify the signed package and device permission in the SDK.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/protected-content"
        },
        "parameters": [
          {
            "name": "product_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "host_version",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "token",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Private customer-account session fallback. Prefer the Authorization header to avoid credentials in URLs."
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: releases.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "releases": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "contentId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "releaseId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "productId": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "name": {
                            "type": "string"
                          },
                          "revision": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "owned": {
                            "type": "boolean"
                          },
                          "included": {
                            "type": "boolean"
                          },
                          "available": {
                            "type": "boolean"
                          },
                          "requiresParent": {
                            "type": "boolean"
                          },
                          "packageHash": {
                            "type": "string"
                          },
                          "manifest": {
                            "type": "object",
                            "properties": {
                              "alg": {
                                "const": "RS256"
                              },
                              "kid": {
                                "type": "string"
                              },
                              "payload": {
                                "type": "string"
                              },
                              "signature": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "required": [
                              "alg",
                              "kid",
                              "payload",
                              "signature"
                            ]
                          },
                          "downloadPath": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "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 session token OR private customer-account token query fallback (prefer Bearer)",
        "x-access-scope": "Signed-in customer-account identity and current permitted store, instrument and content ownership.",
        "x-request-fields": [
          "query product_id: integer (required)",
          "query host_version: string (required)",
          "query token: string. Private customer-account session fallback. Prefer the Authorization header to avoid credentials in URLs."
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.",
        "security": [
          {
            "AccountSession": []
          },
          {
            "CustomerAccountQueryToken": []
          }
        ],
        "x-contract-coverage": "Reviewed 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": [
          "CUSTOMER_ACCOUNT_REQUIRED",
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "CUSTOMER_STORE_CLOSED",
          "LIBRARY_SESSION_REVOKED",
          "SESSION_VERIFICATION_UNAVAILABLE"
        ],
        "x-source-files": [
          "routes/deliveryRoutes.js",
          "controllers/deliveryController.js",
          "services/protectedContentCatalogService.js",
          "services/purchaseOfferLibraryService.js",
          "services/customerLibraryIdentityService.js",
          "services/customerStoreAccessService.js"
        ]
      }
    },
    "/api/delivery/protected-content/{releaseId}": {
      "get": {
        "summary": "Request a private protected-package link",
        "description": "Requires a signed-in customer-account session: use Authorization: Bearer, or the supported private token query fallback. A legacy library/download token alone returns CUSTOMER_ACCOUNT_REQUIRED. Valid store-scoped sessions are limited to their own store; shared-account sessions retain their permitted store/product checks. Never publish token-bearing URLs. host_version is a software compatibility value, not a purchased-major restriction. A catalog entry or download URL does not authorize playback; verify the signed package and device permission in the SDK.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/protected-content"
        },
        "parameters": [
          {
            "name": "releaseId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "product_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "host_version",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "token",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Private customer-account session fallback. Prefer the Authorization header to avoid credentials in URLs."
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: url, filename, expiresIn, contentId, releaseId, packageHash.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "filename": {
                      "type": "string"
                    },
                    "expiresIn": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "contentId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "releaseId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "packageHash": {
                      "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 session token OR private customer-account token query fallback (prefer Bearer)",
        "x-access-scope": "Signed-in customer-account identity and current permitted store, instrument and content ownership.",
        "x-request-fields": [
          "query product_id: integer (required)",
          "query host_version: string (required)",
          "query token: string. Private customer-account session fallback. Prefer the Authorization header to avoid credentials in URLs."
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.",
        "security": [
          {
            "AccountSession": []
          },
          {
            "CustomerAccountQueryToken": []
          }
        ],
        "x-contract-coverage": "Reviewed 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": [
          "CUSTOMER_ACCOUNT_REQUIRED",
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "CUSTOMER_STORE_CLOSED",
          "LIBRARY_SESSION_REVOKED",
          "SESSION_VERIFICATION_UNAVAILABLE"
        ],
        "x-source-files": [
          "routes/deliveryRoutes.js",
          "controllers/deliveryController.js",
          "services/protectedContentCatalogService.js",
          "services/purchaseOfferLibraryService.js",
          "services/customerLibraryIdentityService.js",
          "services/customerStoreAccessService.js"
        ]
      }
    },
    "/api/delivery/protected-content/products/{productId}/versions/{hostVersion}/releases/{releaseId}": {
      "get": {
        "summary": "Download a specific compatible protected release",
        "description": "Requires a signed-in customer-account session: use Authorization: Bearer, or the supported private token query fallback. A legacy library/download token alone returns CUSTOMER_ACCOUNT_REQUIRED. Valid store-scoped sessions are limited to their own store; shared-account sessions retain their permitted store/product checks. Never publish token-bearing URLs.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/protected-content"
        },
        "parameters": [
          {
            "name": "productId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "hostVersion",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "releaseId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "token",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Private customer-account session fallback. Prefer the Authorization header to avoid credentials in URLs."
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: url, filename, expiresIn, contentId, releaseId, packageHash.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "filename": {
                      "type": "string"
                    },
                    "expiresIn": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "contentId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "releaseId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "packageHash": {
                      "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 session token OR private customer-account token query fallback (prefer Bearer)",
        "x-access-scope": "Signed-in customer-account identity and current permitted instrument/content access.",
        "x-request-fields": [
          "query token: string. Private customer-account session fallback. Prefer the Authorization header to avoid credentials in URLs."
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.",
        "security": [
          {
            "AccountSession": []
          },
          {
            "CustomerAccountQueryToken": []
          }
        ],
        "x-contract-coverage": "Reviewed 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": [
          "CUSTOMER_ACCOUNT_REQUIRED",
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "CUSTOMER_STORE_CLOSED",
          "LIBRARY_SESSION_REVOKED",
          "SESSION_VERIFICATION_UNAVAILABLE",
          "CONTENT_ACCESS_REQUIRED",
          "CONTENT_DELIVERY_NOT_READY",
          "CONTENT_HOST_VERSION_REQUIRED"
        ],
        "x-source-files": [
          "routes/deliveryRoutes.js",
          "controllers/deliveryController.js",
          "services/protectedContentCatalogService.js",
          "services/purchaseOfferLibraryService.js",
          "services/customerLibraryIdentityService.js",
          "services/customerStoreAccessService.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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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. Empty selected-product scope returns no rows or counts; product/product_id aliases cannot expand assignment. Productless website events and workspace-wide email events are excluded from product-filtered results. A mixed-product order amount contains only the selected item totals. Customer identity, visitor/session identifiers and customerId filters require customers.view. Serial metadata requires serials.view; order-row id and source_id are null without orders.view. Opaque paths, failure text and nested metadata require customers.view, serials.view, orders.view, entitlements.view and refunds.view together. Field filtering happens before search and its derived summaries, so hidden identities cannot be searched. SQL source counts count records, not distinct customers; type/search/customer filters summarize the bounded candidate rows. 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": "product",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "required": false,
            "description": "Alias of productId with the same assignment checks."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 250,
              "default": 100
            },
            "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",
                        "properties": {
                          "id": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "type": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "detail": {
                            "type": "string"
                          },
                          "source": {
                            "type": "string"
                          },
                          "source_table": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "source_id": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "occurred_at": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "status": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "amount_cents": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "currency": {
                            "type": "string"
                          },
                          "customer": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "id": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "email": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "anonymous_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "session_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            },
                            "additionalProperties": true
                          },
                          "product": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "id": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            },
                            "additionalProperties": true
                          },
                          "campaign": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "id": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            },
                            "additionalProperties": true
                          },
                          "path": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "channel": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "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 session token",
        "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 product: integer. Alias of productId with the same assignment checks.",
          "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": [
          "developer_team_permission_denied",
          "developer_team_resource_not_found"
        ],
        "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"
                        },
                        "service_option": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "service_option_name": {
                          "type": "string"
                        },
                        "service_active": {
                          "type": "boolean"
                        },
                        "monthly_minimum_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthly_service_fee_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "configured_monthly_minimum_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "configured_monthly_service_fee_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "storage_allowance_bytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "hosting_included": {
                          "type": "boolean"
                        },
                        "checkout_included": {
                          "type": "boolean"
                        },
                        "minimum_qualifying_basis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ]
                        },
                        "minimum_qualifying_activity_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "service_policy_version": {
                          "type": "string"
                        },
                        "developer_service_fee_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "unledgered_service_fee_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
                        },
                        "provider_processing_fees_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "soundsync_charges_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
                        },
                        "marketing_emails": {
                          "type": "object",
                          "properties": {
                            "sent_this_month": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "included": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "monthly_included": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "prior_month_quantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "month_to_date_quantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "remaining_included": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "billable": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "charge_cents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "rate_cents_per_1000": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "current_rate_cents_per_1000": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "pricing_basis": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        },
                        "external_redemptions": {
                          "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 session token",
        "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 session token",
        "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": "Requires all-products workspace scope. source_id is null for orders without orders.view and ledger adjustments without refunds.view; aggregate amounts remain available. 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": [
                              "string",
                              "number",
                              "null"
                            ]
                          },
                          "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 session token",
        "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": "Requires all-products workspace scope. Uses the current America/New_York calendar month, not a requested historical month. 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"
                        },
                        "service_option": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "service_option_name": {
                          "type": "string"
                        },
                        "service_active": {
                          "type": "boolean"
                        },
                        "monthly_minimum_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthly_service_fee_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "configured_monthly_minimum_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "configured_monthly_service_fee_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "storage_allowance_bytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "hosting_included": {
                          "type": "boolean"
                        },
                        "checkout_included": {
                          "type": "boolean"
                        },
                        "minimum_qualifying_basis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ]
                        },
                        "minimum_qualifying_activity_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "service_policy_version": {
                          "type": "string"
                        },
                        "developer_service_fee_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "unledgered_service_fee_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
                        },
                        "provider_processing_fees_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "soundsync_charges_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
                        },
                        "marketing_emails": {
                          "type": "object",
                          "properties": {
                            "sent_this_month": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "included": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "monthly_included": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "prior_month_quantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "month_to_date_quantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "remaining_included": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "billable": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "charge_cents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "rate_cents_per_1000": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "current_rate_cents_per_1000": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "pricing_basis": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        },
                        "external_redemptions": {
                          "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 session token",
        "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": "Requires all-products workspace scope, matching /api/developer/revenue/products. 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 session token",
        "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": "Requires all-products workspace scope. Aggregate customer metrics remain available; customer rows and subscription identities require customers.view. Order activity references require orders.view and ledger adjustment references require refunds.view. 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."
                        },
                        "refund_tax_total_cents": {
                          "type": "integer"
                        },
                        "product_adjustments_cents": {
                          "type": "integer"
                        },
                        "earnings_before_recovery_waivers_cents": {
                          "type": "integer"
                        },
                        "recovery_credit_cents": {
                          "type": "integer"
                        },
                        "net_developer_refund_cents": {
                          "type": "integer"
                        },
                        "payment_processing_fee_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "processing_fee_pending_count": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "net_after_processing_cents": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Unavailable while processing evidence is pending; not a confirmed zero or bank payout."
                        }
                      },
                      "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"
                        },
                        "service_option": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "service_option_name": {
                          "type": "string"
                        },
                        "service_active": {
                          "type": "boolean"
                        },
                        "monthly_minimum_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthly_service_fee_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "configured_monthly_minimum_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "configured_monthly_service_fee_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "storage_allowance_bytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "hosting_included": {
                          "type": "boolean"
                        },
                        "checkout_included": {
                          "type": "boolean"
                        },
                        "minimum_qualifying_basis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ]
                        },
                        "minimum_qualifying_activity_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "service_policy_version": {
                          "type": "string"
                        },
                        "developer_service_fee_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "unledgered_service_fee_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
                        },
                        "provider_processing_fees_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "soundsync_charges_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
                        },
                        "marketing_emails": {
                          "type": "object",
                          "properties": {
                            "sent_this_month": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "included": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "monthly_included": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "prior_month_quantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "month_to_date_quantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "remaining_included": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "billable": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "charge_cents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "rate_cents_per_1000": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "current_rate_cents_per_1000": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "pricing_basis": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        },
                        "external_redemptions": {
                          "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 session token",
        "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/activate-service": {
      "post": {
        "summary": "POST /api/developer/billing/activate-service",
        "description": "",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/evaluation"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: service.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "service": {
                      "type": "object",
                      "properties": {
                        "active": {
                          "type": "boolean"
                        },
                        "id": {
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "agreementId": {
                          "oneOf": [
                            {
                              "type": "integer",
                              "minimum": 1
                            },
                            {
                              "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 session token",
        "x-access-scope": "Developer account owner with billing.manage and all-product scope. Confirms the reviewed agreement under a selection lock. Evaluation cannot activate production.",
        "x-request-fields": [
          "confirmMonthlyPricing: true (required)",
          "serviceAgreementId: value (required). Current service_agreement_id returned by Billing status. A changed agreement requires fresh pricing review."
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host 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/developerBillingCollectionRoutes.js",
          "services/developerServiceOptionService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "confirmMonthlyPricing": {
                    "const": true
                  },
                  "serviceAgreementId": {
                    "oneOf": [
                      {
                        "type": "integer",
                        "minimum": 1
                      },
                      {
                        "type": "string",
                        "pattern": "^[1-9]\\d*$"
                      }
                    ],
                    "description": "Current service_agreement_id returned by Billing status. A changed agreement requires fresh pricing review."
                  }
                },
                "required": [
                  "confirmMonthlyPricing",
                  "serviceAgreementId"
                ],
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/developer/billing/activate-storage": {
      "post": {
        "summary": "Confirm current monthly pricing and activate production storage",
        "description": "Requires billing.view + billing.manage, all-products scope and the actual workspace owner. Send confirmMonthlyPricing:true. The selected service must include hosting; billing and a saved payment method are verified before first activation. Already active services return their current agreement. Starts the existing monthly service pricing, not an immediate card charge, upload, publication or payout. Does not change a role or financial execution flag.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/billing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: service.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "service": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "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"
                }
              }
            }
          },
          "402": {
            "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.",
            "content": {
              "application/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 session token",
        "x-access-scope": "billing.view + billing.manage, all-products scope and the actual workspace owner.",
        "x-request-fields": [
          "confirmMonthlyPricing: 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": [
          "MONTHLY_PRICING_CONFIRMATION_REQUIRED",
          "SERVICE_OPTION_OWNER_REQUIRED",
          "DEVELOPER_SERVICE_OPTION_REQUIRED",
          "DEVELOPER_SERVICE_OPTION_CAPABILITY_REQUIRED",
          "DEVELOPER_COST_PAYMENT_METHOD_REQUIRED",
          "DEVELOPER_COST_BILLING_RESTRICTED",
          "DEVELOPER_COST_BILLING_UNAVAILABLE",
          "DEVELOPER_COST_FUNDING_UNAVAILABLE"
        ],
        "x-source-files": [
          "routes/developerBillingCollectionRoutes.js",
          "services/developerServiceOptionService.js",
          "services/developerBillingGateService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "confirmMonthlyPricing": {
                    "const": true
                  }
                },
                "required": [
                  "confirmMonthlyPricing"
                ],
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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
                          },
                          "payment_processing_fee_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 session token",
        "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 session token",
        "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 session token",
        "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": "The HTTP response wraps the billing object in status; status.status is the account state string. service_active distinguishes production activation from saved setup. configured_monthly_* describes the agreed option, while monthly_* can be zero before activation. Full Store uses a minimum adjustment, not a second subscription charge; fixed options use their separate service fee. hold_days is an approximate legacy display field: use payout_window_policy and assigned Eastern sales periods rather than computing a rolling release date from it. 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
                        },
                        "service_option": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "service_option_name": {
                          "type": "string"
                        },
                        "service_active": {
                          "type": "boolean"
                        },
                        "monthly_minimum_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthly_service_fee_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "configured_monthly_minimum_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "configured_monthly_service_fee_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "storage_allowance_bytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "hosting_included": {
                          "type": "boolean"
                        },
                        "checkout_included": {
                          "type": "boolean"
                        },
                        "minimum_qualifying_basis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ]
                        },
                        "minimum_qualifying_activity_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "projected_service_fee_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "billing_cycle": {
                          "type": "object",
                          "properties": {
                            "cadence": {
                              "const": "calendar_month"
                            },
                            "payout_run_days": {
                              "type": "array",
                              "items": {
                                "type": "integer",
                                "enum": [
                                  1,
                                  15
                                ]
                              }
                            },
                            "hold_days": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "hold_is_approximate": {
                              "type": "boolean"
                            },
                            "payout_window_policy": {
                              "type": "string"
                            },
                            "period_strategy": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        },
                        "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."
                        },
                        "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"
                            },
                            "service_option": {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            "service_option_name": {
                              "type": "string"
                            },
                            "service_active": {
                              "type": "boolean"
                            },
                            "monthly_minimum_cents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "monthly_service_fee_cents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "configured_monthly_minimum_cents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "configured_monthly_service_fee_cents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "storage_allowance_bytes": {
                              "type": "integer",
                              "minimum": 0,
                              "description": "Bytes, not GB. Current service allowances use decimal GB."
                            },
                            "hosting_included": {
                              "type": "boolean"
                            },
                            "checkout_included": {
                              "type": "boolean"
                            },
                            "minimum_qualifying_basis": {
                              "type": "string",
                              "enum": [
                                "sales_fees",
                                "soundsync_charges"
                              ]
                            },
                            "minimum_qualifying_activity_cents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "service_policy_version": {
                              "type": "string"
                            },
                            "developer_service_fee_cents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "unledgered_service_fee_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
                            },
                            "provider_processing_fees_cents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "soundsync_charges_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
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "sent_this_month": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "included": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "monthly_included": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "prior_month_quantity": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "month_to_date_quantity": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "remaining_included": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "billable": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "charge_cents": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                },
                                "current_rate_cents_per_1000": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "pricing_basis": {
                                  "type": "string"
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "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
                        },
                        "current_balance_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "can_activate_storage": {
                          "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 session token",
        "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",
          "services/developerBillingChargeService.js",
          "services/developerServiceOptionService.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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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/commerce-integrations": {
      "get": {
        "summary": "List provider connections, mappings and recent integration activity",
        "description": "External one-time perpetual licensing only. No external gross sales, payment processing, tax, monetary refund or payout balance is created in SoundSync. Test connections simulate keys without usable licenses or financial entries. Confirmed Live units record idempotent external-redemption usage. Configuration checks are not hosted provider tests. Setup responses contain private credentials and must not be logged, shared or cached. All responses use Cache-Control: no-store.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/commerce-integrations"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "200: Inspect the response schema and conditional states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "providers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "connections": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": [
                              "integer",
                              "string"
                            ]
                          },
                          "publicId": {
                            "type": "string"
                          },
                          "provider": {
                            "type": "string",
                            "enum": [
                              "fastspring",
                              "gumroad",
                              "woocommerce"
                            ]
                          },
                          "environment": {
                            "type": "string",
                            "enum": [
                              "test",
                              "live"
                            ]
                          },
                          "name": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "draft",
                              "active",
                              "paused"
                            ]
                          },
                          "configurationCheckedAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "providerSeenAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "createdAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "mappings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "orders": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "products": {
                      "type": "array",
                      "items": {
                        "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 session token",
        "x-access-scope": "api_keys.manage and all-products scope in the selected developer workspace; connection, event and product ownership 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/commerceIntegrationRoutes.js",
          "services/commerceIntegrationService.js",
          "services/commerceConnectors/index.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      },
      "post": {
        "summary": "Create a draft provider connection",
        "description": "External one-time perpetual licensing only. No external gross sales, payment processing, tax, monetary refund or payout balance is created in SoundSync. Test connections simulate keys without usable licenses or financial entries. Confirmed Live units record idempotent external-redemption usage. Configuration checks are not hosted provider tests. Setup responses contain private credentials and must not be logged, shared or cached. All responses use Cache-Control: no-store.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/commerce-integrations"
        },
        "parameters": [],
        "responses": {
          "201": {
            "description": "201: Inspect the response schema and conditional states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connection": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": [
                            "integer",
                            "string"
                          ]
                        },
                        "publicId": {
                          "type": "string"
                        },
                        "provider": {
                          "type": "string",
                          "enum": [
                            "fastspring",
                            "gumroad",
                            "woocommerce"
                          ]
                        },
                        "environment": {
                          "type": "string",
                          "enum": [
                            "test",
                            "live"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "active",
                            "paused"
                          ]
                        },
                        "configurationCheckedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "providerSeenAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "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"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "api_keys.manage and all-products scope in the selected developer workspace; connection, event and product ownership are checked.",
        "x-request-fields": [
          "provider: fastspring | gumroad | woocommerce",
          "environment: test | live (required)",
          "name: 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/commerceIntegrationRoutes.js",
          "services/commerceIntegrationService.js",
          "services/commerceConnectors/index.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "provider": {
                    "type": "string",
                    "enum": [
                      "fastspring",
                      "gumroad",
                      "woocommerce"
                    ]
                  },
                  "environment": {
                    "type": "string",
                    "enum": [
                      "test",
                      "live"
                    ]
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 80
                  }
                },
                "additionalProperties": true,
                "required": [
                  "environment"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/commerce-integrations/{id}/check": {
      "post": {
        "summary": "Check saved mappings and configuration",
        "description": "External one-time perpetual licensing only. No external gross sales, payment processing, tax, monetary refund or payout balance is created in SoundSync. Test connections simulate keys without usable licenses or financial entries. Confirmed Live units record idempotent external-redemption usage. Configuration checks are not hosted provider tests. Setup responses contain private credentials and must not be logged, shared or cached. All responses use Cache-Control: no-store. Does not contact the provider or prove a purchase. providerVerified reports whether an authenticated provider request was seen; it is separate from the configuration check.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/commerce-integrations"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200: Inspect the response schema and conditional states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    },
                    "providerVerified": {
                      "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 session token",
        "x-access-scope": "api_keys.manage and all-products scope in the selected developer workspace; connection, event and product ownership 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/commerceIntegrationRoutes.js",
          "services/commerceIntegrationService.js",
          "services/commerceConnectors/index.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/api/developer/commerce-integrations/{id}/credentials": {
      "post": {
        "summary": "Save private provider configuration",
        "description": "External one-time perpetual licensing only. No external gross sales, payment processing, tax, monetary refund or payout balance is created in SoundSync. Test connections simulate keys without usable licenses or financial entries. Confirmed Live units record idempotent external-redemption usage. Configuration checks are not hosted provider tests. Setup responses contain private credentials and must not be logged, shared or cached. All responses use Cache-Control: no-store. Gumroad requires a view_sales token and verifies the seller against its fixed API host; WooCommerce requires the HTTPS store origin. FastSpring credentials are generated by setup instead. No single request schema requires both provider-specific fields. Reconfiguration returns the connection to draft.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/commerce-integrations"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200: Inspect the response schema and conditional states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connection": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": [
                            "integer",
                            "string"
                          ]
                        },
                        "publicId": {
                          "type": "string"
                        },
                        "provider": {
                          "type": "string",
                          "enum": [
                            "fastspring",
                            "gumroad",
                            "woocommerce"
                          ]
                        },
                        "environment": {
                          "type": "string",
                          "enum": [
                            "test",
                            "live"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "active",
                            "paused"
                          ]
                        },
                        "configurationCheckedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "providerSeenAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "createdAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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 session token",
        "x-access-scope": "api_keys.manage and all-products scope in the selected developer workspace; connection, event and product ownership are checked.",
        "x-request-fields": [
          "accessToken: string",
          "storeOrigin: 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/commerceIntegrationRoutes.js",
          "services/commerceIntegrationService.js",
          "services/commerceConnectors/index.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "accessToken": {
                    "type": "string"
                  },
                  "storeOrigin": {
                    "type": "string"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/developer/commerce-integrations/{id}/mappings": {
      "post": {
        "summary": "Save a provider product mapping",
        "description": "External one-time perpetual licensing only. No external gross sales, payment processing, tax, monetary refund or payout balance is created in SoundSync. Test connections simulate keys without usable licenses or financial entries. Confirmed Live units record idempotent external-redemption usage. Configuration checks are not hosted provider tests. Setup responses contain private credentials and must not be logged, shared or cached. All responses use Cache-Control: no-store. FastSpring uses product path, Gumroad API product_id, WooCommerce numeric product/variation ID. Product must be owned, available and serial-enabled, without a subscription, bundle or expansion. Saving invalidates the prior configuration check and moves an active connection to draft. checkoutUrl must use the allowed provider/store origin.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/commerce-integrations"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200: Inspect the response schema and conditional states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "mapping": {
                      "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"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "api_keys.manage and all-products scope in the selected developer workspace; connection, event and product ownership are checked.",
        "x-request-fields": [
          "externalProduct: string (required)",
          "productId: integer (required)",
          "enabled: boolean",
          "checkoutUrl: 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/commerceIntegrationRoutes.js",
          "services/commerceIntegrationService.js",
          "services/commerceConnectors/index.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "externalProduct": {
                    "type": "string"
                  },
                  "productId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "enabled": {
                    "type": "boolean"
                  },
                  "checkoutUrl": {
                    "type": "string"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "externalProduct",
                  "productId"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/commerce-integrations/{id}/setup": {
      "get": {
        "summary": "Read private fulfillment and webhook instructions",
        "description": "External one-time perpetual licensing only. No external gross sales, payment processing, tax, monetary refund or payout balance is created in SoundSync. Test connections simulate keys without usable licenses or financial entries. Confirmed Live units record idempotent external-redemption usage. Configuration checks are not hosted provider tests. Setup responses contain private credentials and must not be logged, shared or cached. All responses use Cache-Control: no-store.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/commerce-integrations"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200: Inspect the response schema and conditional states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connection": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": [
                            "integer",
                            "string"
                          ]
                        },
                        "publicId": {
                          "type": "string"
                        },
                        "provider": {
                          "type": "string",
                          "enum": [
                            "fastspring",
                            "gumroad",
                            "woocommerce"
                          ]
                        },
                        "environment": {
                          "type": "string",
                          "enum": [
                            "test",
                            "live"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "active",
                            "paused"
                          ]
                        },
                        "configurationCheckedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "providerSeenAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "createdAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "products": {
                      "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"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "api_keys.manage and all-products scope in the selected developer workspace; connection, event and product ownership 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/commerceIntegrationRoutes.js",
          "services/commerceIntegrationService.js",
          "services/commerceConnectors/index.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/api/developer/commerce-integrations/{id}/status": {
      "post": {
        "summary": "Enable checked fulfillment or pause new issuance",
        "description": "External one-time perpetual licensing only. No external gross sales, payment processing, tax, monetary refund or payout balance is created in SoundSync. Test connections simulate keys without usable licenses or financial entries. Confirmed Live units record idempotent external-redemption usage. Configuration checks are not hosted provider tests. Setup responses contain private credentials and must not be logged, shared or cached. All responses use Cache-Control: no-store. Enabling requires current configuration check and valid mappings. Pause blocks new fulfillment; authenticated return/revocation handling remains separate.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/commerce-integrations"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200: Inspect the response schema and conditional states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connection": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": [
                            "integer",
                            "string"
                          ]
                        },
                        "publicId": {
                          "type": "string"
                        },
                        "provider": {
                          "type": "string",
                          "enum": [
                            "fastspring",
                            "gumroad",
                            "woocommerce"
                          ]
                        },
                        "environment": {
                          "type": "string",
                          "enum": [
                            "test",
                            "live"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "active",
                            "paused"
                          ]
                        },
                        "configurationCheckedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "providerSeenAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "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"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "api_keys.manage and all-products scope in the selected developer workspace; connection, event and product ownership are checked.",
        "x-request-fields": [
          "status: active | paused (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/commerceIntegrationRoutes.js",
          "services/commerceIntegrationService.js",
          "services/commerceConnectors/index.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "paused"
                    ]
                  }
                },
                "additionalProperties": true,
                "required": [
                  "status"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/commerce-integrations/events/{id}/retry": {
      "post": {
        "summary": "Retry the original stored authenticated event",
        "description": "External one-time perpetual licensing only. No external gross sales, payment processing, tax, monetary refund or payout balance is created in SoundSync. Test connections simulate keys without usable licenses or financial entries. Confirmed Live units record idempotent external-redemption usage. Configuration checks are not hosted provider tests. Setup responses contain private credentials and must not be logged, shared or cached. All responses use Cache-Control: no-store. Retry uses the stored original payload after correcting the cause. It does not send a provider purchase or refund request, and duplicate issuance remains protected.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/commerce-integrations"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200: Inspect the response schema and conditional states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "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"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "api_keys.manage and all-products scope in the selected developer workspace; connection, event and product ownership 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/commerceIntegrationRoutes.js",
          "services/commerceIntegrationService.js",
          "services/commerceConnectors/index.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/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": "all, 1d, 1w, 2w, 1m or custom. Legacy YYYY-MM-DD_to_YYYY-MM-DD is supported. Non-custom presets clear stale calendar dates."
          },
          {
            "name": "dateFrom",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": false,
            "description": "Inclusive UTC calendar start, not the Eastern accounting month."
          },
          {
            "name": "dateTo",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": false,
            "description": "Inclusive UTC calendar end; the SQL upper bound is the next midnight."
          },
          {
            "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 session token",
        "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. all, 1d, 1w, 2w, 1m or custom. Legacy YYYY-MM-DD_to_YYYY-MM-DD is supported. Non-custom presets clear stale calendar dates.",
          "query dateFrom: string. Inclusive UTC calendar start, not the Eastern accounting month.",
          "query dateTo: string. Inclusive UTC calendar end; the SQL upper bound is the next midnight.",
          "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": "Close a customer account at this store",
        "description": "Requires customers.manage, all-products workspace scope and confirm:true or confirmation:\"yes\". Marks this store relationship blocked/closed, stops its pending marketing and measurement, and retains required purchase/financial history. Store access returns CUSTOMER_STORE_CLOSED. This is not global account deletion, a refund, closure of another store or automatic erasure of every record. 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, storeAccountClosed, customer_id, developer_customer_id, message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "alreadyRemoved": {
                      "type": "boolean"
                    },
                    "already_removed": {
                      "type": "boolean"
                    },
                    "storeAccountClosed": {
                      "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 session token",
        "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, email, phone and an optional store password affect only this developer relationship. Marketing contacts, supported queued messages and current contact references follow that store edit, with later activity/imports retaining its corrected details. Shared SoundSync login credentials, verification, recovery, Stripe billing identity and other stores are not edited. Store email/password changes invalidate old store credential sessions and reset links only. Names can be cleared independently; first_name/last_name and generatedPassword/generated_password compatibility aliases remain accepted. Unlinked contacts cannot receive a login password until an account is linked. Issued invoices, access ownership and sent messages are not rewritten; saved suppressions remain protected.",
        "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, scope, passwordChanged, password_changed, customer.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    },
                    "scope": {
                      "const": "storefront"
                    },
                    "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 session token",
        "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",
          "newPassword: string. Optional replacement store password, at most 72 UTF-8 bytes. Never log it.",
          "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_CONTACT_CONFLICT",
          "INVALID_CUSTOMER_PASSWORD"
        ],
        "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"
                    ]
                  },
                  "newPassword": {
                    "type": "string",
                    "minLength": 8,
                    "description": "Optional replacement store password, at most 72 UTF-8 bytes. Never log it."
                  },
                  "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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}/product-access/{productId}/restore": {
      "post": {
        "summary": "Restore the selected customer entitlement",
        "description": "A real support access change, not a preview or refund. Optional reason is saved in access metadata and the activity log. suspend sets the entitlement to suspended, revoke to revoked, and restore to active with revoked_at cleared. Matching serial_status follows the action, but restore does not clear an existing serial revoked flag. No payment, account deletion, global suspension or immediate communication with offline devices is performed. Already issued offline authorizations retain their own expiry and reconnect rules.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/platform-tools"
        },
        "parameters": [
          {
            "name": "customerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "productId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: access.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access": {
                      "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": {
                          "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."
                        },
                        "customer_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."
                        },
                        "product_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."
                        },
                        "state": {
                          "type": "string",
                          "enum": [
                            "active",
                            "suspended",
                            "revoked"
                          ]
                        },
                        "revoked_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 session token",
        "x-access-scope": "entitlements.manage and assigned-product access; both the customer relationship and product must belong to the effective workspace.",
        "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/developerPlatformToolsRoutes.js",
          "services/betaPlatformToolsService.js"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/developer/customers/{customerId}/product-access/{productId}/revoke": {
      "post": {
        "summary": "Revoke the selected customer entitlement",
        "description": "A real support access change, not a preview or refund. Optional reason is saved in access metadata and the activity log. suspend sets the entitlement to suspended, revoke to revoked, and restore to active with revoked_at cleared. Matching serial_status follows the action, but restore does not clear an existing serial revoked flag. No payment, account deletion, global suspension or immediate communication with offline devices is performed. Already issued offline authorizations retain their own expiry and reconnect rules.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/platform-tools"
        },
        "parameters": [
          {
            "name": "customerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "productId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: access.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access": {
                      "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": {
                          "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."
                        },
                        "customer_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."
                        },
                        "product_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."
                        },
                        "state": {
                          "type": "string",
                          "enum": [
                            "active",
                            "suspended",
                            "revoked"
                          ]
                        },
                        "revoked_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 session token",
        "x-access-scope": "entitlements.manage and assigned-product access; both the customer relationship and product must belong to the effective workspace.",
        "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/developerPlatformToolsRoutes.js",
          "services/betaPlatformToolsService.js"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/developer/customers/{customerId}/product-access/{productId}/suspend": {
      "post": {
        "summary": "Suspend the selected customer entitlement",
        "description": "A real support access change, not a preview or refund. Optional reason is saved in access metadata and the activity log. suspend sets the entitlement to suspended, revoke to revoked, and restore to active with revoked_at cleared. Matching serial_status follows the action, but restore does not clear an existing serial revoked flag. No payment, account deletion, global suspension or immediate communication with offline devices is performed. Already issued offline authorizations retain their own expiry and reconnect rules.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/platform-tools"
        },
        "parameters": [
          {
            "name": "customerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "productId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: access.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access": {
                      "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": {
                          "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."
                        },
                        "customer_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."
                        },
                        "product_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."
                        },
                        "state": {
                          "type": "string",
                          "enum": [
                            "active",
                            "suspended",
                            "revoked"
                          ]
                        },
                        "revoked_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 session token",
        "x-access-scope": "entitlements.manage and assigned-product access; both the customer relationship and product must belong to the effective workspace.",
        "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/developerPlatformToolsRoutes.js",
          "services/betaPlatformToolsService.js"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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": "Exports all matching authorized records from a stable read-only snapshot; page and limit do not restrict the export to the current screen. All three tables accept dateFrom/dateTo. Customer dates use signup/relationship creation; redeemed serials use redemption and available serials creation; purchases use their source event. Custom calendar bounds are inclusive UTC dates, not Eastern billing buckets. Purchases preserve Purchase Record ID, displayed Order ID and Reseller Order ID separately and can expand a grouped record into multiple item rows. completedRecords counts logical source records/groups, not necessarily CSV lines. With NDJSON, accumulate type:chunk csv fields, require type:complete after commit, and discard partial output on type:error or a disconnected stream. An HTTP 200 before completion is not a successful complete export. CSV remains private, no-store.",
        "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": "all, 1d, 1w, 2w, 1m or custom. Legacy YYYY-MM-DD_to_YYYY-MM-DD is supported. Non-custom presets clear stale calendar dates."
          },
          {
            "name": "dateFrom",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": false,
            "description": "Inclusive UTC calendar start, not the Eastern accounting month."
          },
          {
            "name": "dateTo",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": false,
            "description": "Inclusive UTC calendar end; the SQL upper bound is the next midnight."
          },
          {
            "name": "productId",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "required": false,
            "description": ""
          },
          {
            "in": "header",
            "name": "Accept",
            "schema": {
              "type": "string",
              "enum": [
                "text/csv",
                "application/x-ndjson"
              ]
            },
            "description": "Use application/x-ndjson for progress framing, otherwise receive plain CSV."
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: text/csv.",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/x-ndjson": {
                "schema": {
                  "type": "string",
                  "description": "Newline-delimited chunk, complete or error frames. A chunk contains csv, completedRecords and totalRecords. Completion is required before offering the accumulated CSV."
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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. all, 1d, 1w, 2w, 1m or custom. Legacy YYYY-MM-DD_to_YYYY-MM-DD is supported. Non-custom presets clear stale calendar dates.",
          "query dateFrom: string. Inclusive UTC calendar start, not the Eastern accounting month.",
          "query dateTo: string. Inclusive UTC calendar end; the SQL upper bound is the next midnight.",
          "query productId: integer",
          "header Accept: string. Use application/x-ndjson for progress framing, otherwise receive plain CSV."
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.",
        "security": [
          {
            "AccountSession": []
          }
        ],
        "x-contract-coverage": "Reviewed field schemas; inspect 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/customerTableDateFilter.js",
          "services/customerExportReadContext.js",
          "services/purchaseExportPager.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 session token",
        "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/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. Active compatibility alias of /api/dashboard with the same handlers and permission checks; prefer the canonical /api/dashboard path for new clients.",
        "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 session token",
        "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/developer/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. Active compatibility alias of /api/dashboard with the same handlers and permission checks; prefer the canonical /api/dashboard path for new clients.",
        "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 session token",
        "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 America/New_York 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. Active compatibility alias of /api/dashboard with the same handlers and permission checks; prefer the canonical /api/dashboard path for new clients.",
        "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 session token",
        "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/developer/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. Active compatibility alias of /api/dashboard with the same handlers and permission checks; prefer the canonical /api/dashboard path for new clients.",
        "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 session token",
        "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/developer/earnings/adjustments-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/adjustments-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/adjustments-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "INVALID_ALLOCATION_STATE",
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/earnings/balance": {
      "get": {
        "summary": "GET /api/developer/settlements/balance",
        "description": "Active compatibility alias of GET /api/developer/settlements/balance. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. Can initialize a local settlement account, recalculate balances and refresh a configured Stripe Connect account. Not a zero-write uptime probe. payout_ready is an account/destination status, not approval to send, a guaranteed net amount or confirmed bank receipt. No transfer or automatic-execution setting is changed.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/billing"
        },
        "parameters": [
          {
            "name": "currency",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "usd"
            }
          },
          {
            "name": "environment",
            "in": "query",
            "schema": {
              "enum": [
                "live",
                "test"
              ],
              "default": "live"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "billing.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/developerSettlementRoutes.js",
          "services/payoutSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/earnings/bank-payouts": {
      "get": {
        "summary": "GET /api/developer/settlements/bank-payouts",
        "description": "Active compatibility alias of GET /api/developer/settlements/bank-payouts. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/connectPayoutService.js"
        ]
      }
    },
    "/api/developer/earnings/batches": {
      "get": {
        "summary": "GET /api/developer/settlements/batches",
        "description": "Active compatibility alias of GET /api/developer/settlements/batches. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary.",
        "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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "billing.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/developerSettlementRoutes.js",
          "services/payoutSettlementService.js"
        ]
      }
    },
    "/api/developer/earnings/connect-session": {
      "post": {
        "summary": "POST /api/developer/settlements/connect-session",
        "description": "Active compatibility alias of POST /api/developer/settlements/connect-session. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/billing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "billing.view and all-products workspace scope; effective developer ownership. Workspace owner only for this setup 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": [
          {
            "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/earnings/earnings/adjustments-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/adjustments-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/adjustments-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "INVALID_ALLOCATION_STATE",
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/earnings/earnings/recovery/cases": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/cases",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/cases. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "MOR_RECOVERY_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/earnings/earnings/recovery/cases/{id}": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/cases/{id}",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/cases/{id}. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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/earnings/earnings/recovery/offsets": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/offsets",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/offsets. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/earnings/earnings/recovery/reserve": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/reserve",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/reserve. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "MOR_RECOVERY_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/earnings/earnings/recovery/statements": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/statements",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/statements. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/earnings/earnings/recovery/summary": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/summary",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/summary. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/earnings/earnings/settlements-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/settlements-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/settlements-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "INVALID_ALLOCATION_STATE",
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/earnings/earnings/statements-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/statements-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/statements-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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 Eastern calendar 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": "See the linked operation reference for the response contract.",
            "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",
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "period_start": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "period_end": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "marketing_email_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "redemption_overage_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_adjustment_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "developer_service_fee_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "provider_processing_fees_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "non_sale_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_qualifying_basis": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "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": "AccountSession",
        "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": [
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/earnings/earnings/summary-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/summary-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/summary-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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 Eastern calendar 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": "See the linked operation reference for the response contract.",
            "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",
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "period_start": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "period_end": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "marketing_email_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "redemption_overage_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_adjustment_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "developer_service_fee_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "provider_processing_fees_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "non_sale_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_qualifying_basis": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "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": "AccountSession",
        "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": [
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/earnings/earnings/transactions-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/transactions-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/transactions-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "INVALID_ALLOCATION_STATE",
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/earnings/history": {
      "get": {
        "summary": "GET /api/developer/settlements/history",
        "description": "Active compatibility alias of GET /api/developer/settlements/history. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. Transfer payout_fee records distinguish the original deduction, actual provider fee, prior adjustment, estimated cross-border component and FX quote/settlement. Pending or unclaimed payment is not bank receipt; unreserved fee adjustments can change a later payout.",
        "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": "See the linked operation reference for the response contract.",
            "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
                                },
                                "provider": {
                                  "type": "string"
                                },
                                "payout_fee": {
                                  "anyOf": [
                                    {
                                      "type": "object",
                                      "properties": {
                                        "feeCents": {
                                          "type": "integer",
                                          "minimum": 0
                                        },
                                        "actualFeeCents": {
                                          "anyOf": [
                                            {
                                              "type": "integer",
                                              "minimum": 0
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        },
                                        "adjustmentCents": {
                                          "type": "integer"
                                        },
                                        "differenceCents": {
                                          "anyOf": [
                                            {
                                              "type": "integer"
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        },
                                        "status": {
                                          "type": "string"
                                        },
                                        "feeComponents": {
                                          "type": "array",
                                          "items": {
                                            "type": "object",
                                            "properties": {
                                              "id": {
                                                "type": "string"
                                              },
                                              "kind": {
                                                "type": "string"
                                              },
                                              "basis": {
                                                "type": "string"
                                              },
                                              "amountCents": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "additionalProperties": true
                                          }
                                        },
                                        "crossBorderEstimated": {
                                          "type": "boolean"
                                        },
                                        "crossBorderFeeCents": {
                                          "type": "integer",
                                          "minimum": 0
                                        },
                                        "crossBorderEstimateBasisPoints": {
                                          "anyOf": [
                                            {
                                              "type": "integer",
                                              "minimum": 0
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        },
                                        "fx": {
                                          "anyOf": [
                                            {
                                              "type": "object",
                                              "properties": {
                                                "currency": {
                                                  "type": "string"
                                                },
                                                "localNetMinor": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "actualLocalNetMinor": {
                                                  "anyOf": [
                                                    {
                                                      "type": "integer",
                                                      "minimum": 0
                                                    },
                                                    {
                                                      "type": "null"
                                                    }
                                                  ]
                                                },
                                                "conversionFeeCents": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "actualExchangeRate": {
                                                  "type": "string"
                                                },
                                                "quote": {
                                                  "type": "object",
                                                  "properties": {
                                                    "id": {
                                                      "type": "string"
                                                    },
                                                    "exchangeRate": {
                                                      "type": "string"
                                                    },
                                                    "expiresAt": {
                                                      "type": "string",
                                                      "format": "date-time"
                                                    }
                                                  },
                                                  "additionalProperties": true
                                                },
                                                "settlementVerified": {
                                                  "type": "boolean"
                                                }
                                              },
                                              "additionalProperties": true
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        }
                                      },
                                      "additionalProperties": true
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "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
                      }
                    },
                    "pendingFeeAdjustmentCents": {
                      "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/payoutHistoryReportingService.js",
          "services/revenueReportingScope.js",
          "services/developerPayoutFeeDisclosure.js"
        ]
      }
    },
    "/api/developer/earnings/history/export.csv": {
      "get": {
        "summary": "GET /api/developer/settlements/history/export.csv",
        "description": "Active compatibility alias of GET /api/developer/settlements/history/export.csv. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. The 28 columns, in order, are: Batch, Currency, First sale UTC, Last sale UTC, Scheduled run, Batch earnings cents, Batch status, Invoice offset cents, Transfer reference, Net payout cents, Transfer status, Bank reference, Bank status, Original payout fee deduction cents, Actual payout fee cents, Prior fee adjustment cents, Fee status, Cross-border fee estimated, Cross-border estimate cents included, Cross-border estimate basis points, Quoted FX cost USD cents, Recorded exchange rate, Local payout currency, Recorded local net minor units, FX quote expiry UTC, Conversion status, Fee difference cents, Reconciliation status. Net payout cents is the recorded transfer amount, not gross sale proceeds or guaranteed bank receipt. Actual fee and reconciliation fields can be unavailable until the provider record exists; an empty value is not a confirmed zero. Quoted FX cost is already included in its quoted conversion, not an instruction to subtract it twice. Cross-border estimate cents included is already part of the original deduction. Current accounting is USD; Recorded local net minor units instead uses Local payout currency. Conversion status is confirmed only for a verified settlement, expired_quote for an expired or imminent-expiry quote, unavailable for missing/invalid quote expiry, and quoted for a quote outside that expiry boundary. No FX record leaves this column empty. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/payoutHistoryReportingService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/earnings/ledger": {
      "get": {
        "summary": "GET /api/developer/settlements/ledger",
        "description": "Active compatibility alias of GET /api/developer/settlements/ledger. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary.",
        "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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "billing.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/developerSettlementRoutes.js",
          "services/payoutSettlementService.js"
        ]
      }
    },
    "/api/developer/earnings/payout-email/send-code": {
      "post": {
        "summary": "Send a private verification code to the proposed PayPal payout email",
        "description": "Active compatibility alias of POST /api/developer/settlements/payout-email/send-code. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. Eight-digit code, fifteen-minute expiry, one-minute resend cooldown and five sends per hour. Sends a transactional email. It does not change the active destination or prove PayPal eligibility. verification:null means the delivery result no longer matches an active request, for example because the provider was switched during sending. Do not mark that email verified or silently resend; reload the saved destination and verification state.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/payout-setup"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: verification.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verification": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "email": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string",
                              "enum": [
                                "pending",
                                "verified",
                                "locked",
                                "expired",
                                "delivery_failed"
                              ]
                            },
                            "expiresAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "resendAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "additionalProperties": true
                        },
                        {
                          "type": "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"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "billing.view, all-products workspace scope and workspace owner. These are destination setup operations, not payment approval or sending.",
        "x-request-fields": [
          "email: string (required)",
          "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": [
          "INVALID_PAYPAL_EMAIL",
          "PAYOUT_EMAIL_NOT_VERIFIED",
          "PAYPAL_COUNTRY_UNSUPPORTED",
          "PAYOUT_EMAIL_COOLDOWN",
          "PAYOUT_EMAIL_RATE_LIMIT",
          "PAYOUT_EMAIL_DELIVERY_FAILED"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "services/developerPayoutDestinationService.js",
          "services/developerPayoutEmailVerificationService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 127,
                    "pattern": "^[\\x21-\\x7e]+$"
                  },
                  "environment": {
                    "type": "string",
                    "enum": [
                      "test",
                      "live"
                    ]
                  }
                },
                "additionalProperties": true,
                "required": [
                  "email"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/earnings/payout-email/verify": {
      "post": {
        "summary": "Verify the proposed PayPal payout email before saving it",
        "description": "Active compatibility alias of POST /api/developer/settlements/payout-email/verify. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. Five failed attempts lock this code. A successful verification does not save the payout method: complete payout-method separately.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/payout-setup"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: verification.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verification": {
                      "type": "object",
                      "properties": {
                        "email": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "verified",
                            "locked",
                            "expired",
                            "delivery_failed"
                          ]
                        },
                        "expiresAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "resendAt": {
                          "type": "string",
                          "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"
                }
              }
            }
          },
          "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 session token",
        "x-access-scope": "billing.view, all-products workspace scope and workspace owner. These are destination setup operations, not payment approval or sending.",
        "x-request-fields": [
          "email: string (required)",
          "code: string (required)",
          "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": [
          "INVALID_PAYPAL_EMAIL",
          "PAYOUT_EMAIL_CODE_EXPIRED",
          "PAYOUT_EMAIL_CODE_LOCKED",
          "PAYOUT_EMAIL_CODE_INVALID"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "services/developerPayoutDestinationService.js",
          "services/developerPayoutEmailVerificationService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 127,
                    "pattern": "^[\\x21-\\x7e]+$"
                  },
                  "code": {
                    "type": "string",
                    "pattern": "^[0-9]{8}$"
                  },
                  "environment": {
                    "type": "string",
                    "enum": [
                      "test",
                      "live"
                    ]
                  }
                },
                "additionalProperties": true,
                "required": [
                  "email",
                  "code"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/earnings/payout-method": {
      "post": {
        "summary": "Select one Stripe or PayPal developer payout destination",
        "description": "Active compatibility alias of POST /api/developer/settlements/payout-method. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. For PayPal, verify the SoundSync account and payout email first, provide the registered PayPal country, and confirm account ownership/ability to receive USD. paypalEmail takes precedence over the email alias; an existing saved PayPal email may be reused when neither is sent. Confirmation must be true. Changing a destination can impose a 24-hour wait. In-progress payments block provider switching. PayPal Payouts is approved in production; recipient eligibility, provider requirements and funding still apply. Inbox verification and destination saving do not send money or establish a completed payout. Stripe local settlement does not change USD accounting.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/payout-setup"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: provider, currency, environment, connection.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "provider": {
                      "type": "string",
                      "enum": [
                        "stripe",
                        "paypal"
                      ]
                    },
                    "currency": {
                      "const": "usd"
                    },
                    "environment": {
                      "type": "string"
                    },
                    "connection": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {},
                          "additionalProperties": true
                        },
                        {
                          "type": "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 session token",
        "x-access-scope": "billing.view, all-products workspace scope and workspace owner. These are destination setup operations, not payment approval or sending.",
        "x-request-fields": [
          "provider: stripe | paypal (required)",
          "environment: test | live",
          "paypalEmail: string",
          "email: string. Supported alias for paypalEmail.",
          "paypalAccountCountry: string",
          "confirmPayPalAccount: 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": [
          "PAYPAL_ACCOUNT_CONFIRMATION_REQUIRED",
          "PAYPAL_EMAIL_VERIFICATION_REQUIRED",
          "PAYPAL_ACCOUNT_COUNTRY_REQUIRED",
          "PAYOUT_EMAIL_NOT_VERIFIED",
          "PAYPAL_COUNTRY_UNSUPPORTED",
          "PAYPAL_PAYOUTS_DISABLED",
          "PAYOUT_IN_PROGRESS",
          "STRIPE_USD_PAYOUT_COUNTRY_UNAVAILABLE"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "services/developerPayoutDestinationService.js",
          "services/developerPayoutEmailVerificationService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "provider": {
                    "type": "string",
                    "enum": [
                      "stripe",
                      "paypal"
                    ]
                  },
                  "environment": {
                    "type": "string",
                    "enum": [
                      "test",
                      "live"
                    ]
                  },
                  "paypalEmail": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 127,
                    "pattern": "^[\\x21-\\x7e]+$"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 127,
                    "pattern": "^[\\x21-\\x7e]+$",
                    "description": "Supported alias for paypalEmail."
                  },
                  "paypalAccountCountry": {
                    "type": "string"
                  },
                  "confirmPayPalAccount": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "provider"
                ],
                "allOf": [
                  {
                    "if": {
                      "properties": {
                        "provider": {
                          "const": "paypal"
                        }
                      },
                      "required": [
                        "provider"
                      ]
                    },
                    "then": {
                      "properties": {
                        "confirmPayPalAccount": {
                          "const": true
                        }
                      },
                      "required": [
                        "confirmPayPalAccount"
                      ]
                    }
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/earnings/payout-readiness": {
      "get": {
        "summary": "GET /api/developer/settlements/payout-readiness",
        "description": "Active compatibility alias of GET /api/developer/settlements/payout-readiness. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. Can initialize a local settlement account, recalculate balances and refresh a configured Stripe Connect account. Not a zero-write uptime probe. payout_ready is an account/destination status, not approval to send, a guaranteed net amount or confirmed bank receipt. No transfer or automatic-execution setting is changed.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/billing"
        },
        "parameters": [
          {
            "name": "currency",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "usd"
            }
          },
          {
            "name": "environment",
            "in": "query",
            "schema": {
              "enum": [
                "live",
                "test"
              ],
              "default": "live"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "billing.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/developerSettlementRoutes.js",
          "services/payoutSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/earnings/payout-status/refresh": {
      "post": {
        "summary": "POST /api/developer/settlements/payout-status/refresh",
        "description": "Active compatibility alias of POST /api/developer/settlements/payout-status/refresh. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "billing.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-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/earnings/payouts/bank-payouts": {
      "get": {
        "summary": "GET /api/developer/settlements/bank-payouts",
        "description": "Active compatibility alias of GET /api/developer/settlements/bank-payouts. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/connectPayoutService.js"
        ]
      }
    },
    "/api/developer/earnings/payouts/history": {
      "get": {
        "summary": "GET /api/developer/settlements/history",
        "description": "Active compatibility alias of GET /api/developer/settlements/history. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. Transfer payout_fee records distinguish the original deduction, actual provider fee, prior adjustment, estimated cross-border component and FX quote/settlement. Pending or unclaimed payment is not bank receipt; unreserved fee adjustments can change a later payout.",
        "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": "See the linked operation reference for the response contract.",
            "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
                                },
                                "provider": {
                                  "type": "string"
                                },
                                "payout_fee": {
                                  "anyOf": [
                                    {
                                      "type": "object",
                                      "properties": {
                                        "feeCents": {
                                          "type": "integer",
                                          "minimum": 0
                                        },
                                        "actualFeeCents": {
                                          "anyOf": [
                                            {
                                              "type": "integer",
                                              "minimum": 0
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        },
                                        "adjustmentCents": {
                                          "type": "integer"
                                        },
                                        "differenceCents": {
                                          "anyOf": [
                                            {
                                              "type": "integer"
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        },
                                        "status": {
                                          "type": "string"
                                        },
                                        "feeComponents": {
                                          "type": "array",
                                          "items": {
                                            "type": "object",
                                            "properties": {
                                              "id": {
                                                "type": "string"
                                              },
                                              "kind": {
                                                "type": "string"
                                              },
                                              "basis": {
                                                "type": "string"
                                              },
                                              "amountCents": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "additionalProperties": true
                                          }
                                        },
                                        "crossBorderEstimated": {
                                          "type": "boolean"
                                        },
                                        "crossBorderFeeCents": {
                                          "type": "integer",
                                          "minimum": 0
                                        },
                                        "crossBorderEstimateBasisPoints": {
                                          "anyOf": [
                                            {
                                              "type": "integer",
                                              "minimum": 0
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        },
                                        "fx": {
                                          "anyOf": [
                                            {
                                              "type": "object",
                                              "properties": {
                                                "currency": {
                                                  "type": "string"
                                                },
                                                "localNetMinor": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "actualLocalNetMinor": {
                                                  "anyOf": [
                                                    {
                                                      "type": "integer",
                                                      "minimum": 0
                                                    },
                                                    {
                                                      "type": "null"
                                                    }
                                                  ]
                                                },
                                                "conversionFeeCents": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "actualExchangeRate": {
                                                  "type": "string"
                                                },
                                                "quote": {
                                                  "type": "object",
                                                  "properties": {
                                                    "id": {
                                                      "type": "string"
                                                    },
                                                    "exchangeRate": {
                                                      "type": "string"
                                                    },
                                                    "expiresAt": {
                                                      "type": "string",
                                                      "format": "date-time"
                                                    }
                                                  },
                                                  "additionalProperties": true
                                                },
                                                "settlementVerified": {
                                                  "type": "boolean"
                                                }
                                              },
                                              "additionalProperties": true
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        }
                                      },
                                      "additionalProperties": true
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "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
                      }
                    },
                    "pendingFeeAdjustmentCents": {
                      "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/payoutHistoryReportingService.js",
          "services/revenueReportingScope.js",
          "services/developerPayoutFeeDisclosure.js"
        ]
      }
    },
    "/api/developer/earnings/payouts/history/export.csv": {
      "get": {
        "summary": "GET /api/developer/settlements/history/export.csv",
        "description": "Active compatibility alias of GET /api/developer/settlements/history/export.csv. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. The 28 columns, in order, are: Batch, Currency, First sale UTC, Last sale UTC, Scheduled run, Batch earnings cents, Batch status, Invoice offset cents, Transfer reference, Net payout cents, Transfer status, Bank reference, Bank status, Original payout fee deduction cents, Actual payout fee cents, Prior fee adjustment cents, Fee status, Cross-border fee estimated, Cross-border estimate cents included, Cross-border estimate basis points, Quoted FX cost USD cents, Recorded exchange rate, Local payout currency, Recorded local net minor units, FX quote expiry UTC, Conversion status, Fee difference cents, Reconciliation status. Net payout cents is the recorded transfer amount, not gross sale proceeds or guaranteed bank receipt. Actual fee and reconciliation fields can be unavailable until the provider record exists; an empty value is not a confirmed zero. Quoted FX cost is already included in its quoted conversion, not an instruction to subtract it twice. Cross-border estimate cents included is already part of the original deduction. Current accounting is USD; Recorded local net minor units instead uses Local payout currency. Conversion status is confirmed only for a verified settlement, expired_quote for an expired or imminent-expiry quote, unavailable for missing/invalid quote expiry, and quoted for a quote outside that expiry boundary. No FX record leaves this column empty. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/payoutHistoryReportingService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/earnings/payouts/summary": {
      "get": {
        "summary": "GET /api/developer/settlements/summary",
        "description": "Active compatibility alias of GET /api/developer/settlements/summary. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. The summary selects the upcoming payout run, not the oldest unpaid run used by owner payment preparation. available_cents belongs to that selected sales period; held_cents can include unpaid earnings outside it or on hold. owed_cents covers the scoped unpaid balance across periods and is not the forecast net or permission to send. unresolved_source_entries/cents identify historical entries without complete order/environment evidence, excluded from confirmed payable totals. payoutForecast is an estimate for the selected Eastern period, not payout eligibility or permission to send: readyToSend is always false. It keeps known sales/usage visible while processingKnown:false leaves processingCents, totalNonSaleCents and netBeforePayoutFeesCents null. A negative net produces amountDueCents rather than a negative transfer. payoutFeePreview can have basis:period_forecast and forecastOnly:true; it is not a completed payment. 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. payoutFeePreview is a read-only projection or prepared amount, not payment execution. The next-run estimate can include recorded earnings that mature by that run. USD accounting, local payout currency, quoted FX cost, estimated provider fees and bank receipt are separate facts. feeComponents preserve each provider component basis and USD-cent amount; actualFeeCents and signed differenceCents are supplied when reconciliation records are available.",
        "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": "See the linked operation reference for the response contract.",
            "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."
                        },
                        "owed_cents": {
                          "type": [
                            "integer",
                            "string"
                          ],
                          "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                        },
                        "source_model": {
                          "type": "string",
                          "enum": [
                            "journal",
                            "legacy"
                          ]
                        },
                        "unresolved_source_entries": {
                          "type": "integer"
                        },
                        "unresolved_source_cents": {
                          "type": [
                            "integer",
                            "string"
                          ],
                          "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                        },
                        "accounting_adjustment_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",
                          "description": "Nominal wait in days. Fixed half-month windows govern eligibility, including short February; this is not an exact rolling hold."
                        },
                        "payout_window_policy": {
                          "type": "string"
                        },
                        "hold_is_approximate": {
                          "type": "boolean"
                        },
                        "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."
                    },
                    "payoutForecast": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "const": "payout-period-forecast-v1"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "available": {
                          "type": "boolean"
                        },
                        "processingKnown": {
                          "type": "boolean"
                        },
                        "pendingProcessingCount": {
                          "type": "integer"
                        },
                        "salesCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "salesFeeCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "earningsBeforeUsageCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "marketingEmailCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "redemptionCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "minimumCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "serviceCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "knownProcessingCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "processingCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "totalNonSaleCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "netBeforePayoutFeesCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "totalDeductionsBeforePayoutFeeCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "amountDueCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "minimumBasis": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "readyToSend": {
                          "const": false
                        },
                        "period_start": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "period_end": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "runDate": {
                          "type": "string",
                          "format": "date"
                        },
                        "charges": {
                          "type": "object",
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "period_start": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "period_end": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "marketing_email_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "redemption_overage_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_adjustment_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "developer_service_fee_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "provider_processing_fees_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "non_sale_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_qualifying_basis": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        },
                        "feePreview": {
                          "type": "object",
                          "properties": {
                            "basis": {
                              "const": "period_forecast"
                            },
                            "projected": {
                              "type": "boolean"
                            },
                            "forecastOnly": {
                              "type": "boolean"
                            },
                            "status": {
                              "type": "string"
                            },
                            "grossCents": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "netCents": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "feeCents": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "currency": {
                              "type": "string"
                            },
                            "provider": {
                              "type": "string"
                            },
                            "country": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "businessCountry": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "payoutCurrency": {
                              "type": "string"
                            },
                            "message": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    },
                    "payoutFeePreview": {
                      "type": "object",
                      "properties": {
                        "enabled": {
                          "type": "boolean"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "waiting",
                            "setup_required",
                            "unavailable",
                            "prepared",
                            "calculated",
                            "estimated"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "currency": {
                          "const": "usd"
                        },
                        "provider": {
                          "type": "string",
                          "enum": [
                            "stripe",
                            "paypal"
                          ]
                        },
                        "country": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "businessCountry": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "payoutCurrency": {
                          "type": "string"
                        },
                        "estimated": {
                          "type": "boolean"
                        },
                        "projected": {
                          "type": "boolean"
                        },
                        "basis": {
                          "type": "string"
                        },
                        "runDate": {
                          "type": "string"
                        },
                        "eligibleAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "transferIntentId": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 1
                            },
                            {
                              "type": "string",
                              "pattern": "^[1-9][0-9]*$"
                            }
                          ]
                        },
                        "grossCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "billingOffsetCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "adjustmentCents": {
                          "type": "integer"
                        },
                        "roundingCarryCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "feeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "netCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "transferFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "crossBorderFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "settlementFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "feeComponents": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "kind": {
                                "type": "string"
                              },
                              "basis": {
                                "type": "string"
                              },
                              "amountCents": {
                                "type": "integer",
                                "minimum": 0
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "conversionFeeCents": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "recipientConversionIncluded": {
                          "type": "boolean"
                        },
                        "monthlyFeePeriod": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "localNetMinor": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "exchangeRate": {
                          "type": "string"
                        },
                        "totalDeveloperFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "netUsdEquivalentCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "fxFeeTreatment": {
                          "type": "string"
                        },
                        "fxQuoteExpiresAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "fxSettled": {
                          "type": "boolean"
                        },
                        "crossBorderEstimated": {
                          "type": "boolean"
                        },
                        "crossBorderEstimateBasisPoints": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "actualFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "differenceCents": {
                          "type": "integer"
                        },
                        "feeReconciled": {
                          "type": "boolean"
                        },
                        "reconciliationStatus": {
                          "type": "string"
                        },
                        "feeDisclosure": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "calculation": {
                          "type": "string"
                        },
                        "period_start": {
                          "type": "string"
                        },
                        "period_end": {
                          "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/transferIntentService.js",
          "services/externalPartnerSalesReportingService.js",
          "services/payoutPeriodForecastService.js",
          "services/actualProcessingFeeService.js",
          "services/developerPayoutPreviewService.js",
          "services/developerStripeLocalPayoutService.js",
          "services/developerPayoutUpfrontRates.js",
          "services/developerPayoutFeeDisclosure.js"
        ]
      }
    },
    "/api/developer/earnings/payouts/transfers": {
      "get": {
        "summary": "GET /api/developer/settlements/transfers",
        "description": "Active compatibility alias of GET /api/developer/settlements/transfers. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/transferIntentService.js"
        ]
      }
    },
    "/api/developer/earnings/payouts/transfers/{id}": {
      "get": {
        "summary": "GET /api/developer/settlements/transfers/{id}",
        "description": "Active compatibility alias of GET /api/developer/settlements/transfers/{id}. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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/earnings/recovery/cases": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/cases",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/cases. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "MOR_RECOVERY_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/earnings/recovery/cases/{id}": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/cases/{id}",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/cases/{id}. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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/earnings/recovery/offsets": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/offsets",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/offsets. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/earnings/recovery/reserve": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/reserve",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/reserve. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "MOR_RECOVERY_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/earnings/recovery/statements": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/statements",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/statements. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/earnings/recovery/summary": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/summary",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/summary. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/earnings/settlements-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/settlements-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/settlements-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "INVALID_ALLOCATION_STATE",
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/earnings/statements-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/statements-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/statements-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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 Eastern calendar 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": "See the linked operation reference for the response contract.",
            "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",
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "period_start": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "period_end": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "marketing_email_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "redemption_overage_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_adjustment_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "developer_service_fee_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "provider_processing_fees_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "non_sale_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_qualifying_basis": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "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": "AccountSession",
        "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": [
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/earnings/summary": {
      "get": {
        "summary": "GET /api/developer/settlements/summary",
        "description": "Active compatibility alias of GET /api/developer/settlements/summary. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. The summary selects the upcoming payout run, not the oldest unpaid run used by owner payment preparation. available_cents belongs to that selected sales period; held_cents can include unpaid earnings outside it or on hold. owed_cents covers the scoped unpaid balance across periods and is not the forecast net or permission to send. unresolved_source_entries/cents identify historical entries without complete order/environment evidence, excluded from confirmed payable totals. payoutForecast is an estimate for the selected Eastern period, not payout eligibility or permission to send: readyToSend is always false. It keeps known sales/usage visible while processingKnown:false leaves processingCents, totalNonSaleCents and netBeforePayoutFeesCents null. A negative net produces amountDueCents rather than a negative transfer. payoutFeePreview can have basis:period_forecast and forecastOnly:true; it is not a completed payment. 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. payoutFeePreview is a read-only projection or prepared amount, not payment execution. The next-run estimate can include recorded earnings that mature by that run. USD accounting, local payout currency, quoted FX cost, estimated provider fees and bank receipt are separate facts. feeComponents preserve each provider component basis and USD-cent amount; actualFeeCents and signed differenceCents are supplied when reconciliation records are available.",
        "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": "See the linked operation reference for the response contract.",
            "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."
                        },
                        "owed_cents": {
                          "type": [
                            "integer",
                            "string"
                          ],
                          "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                        },
                        "source_model": {
                          "type": "string",
                          "enum": [
                            "journal",
                            "legacy"
                          ]
                        },
                        "unresolved_source_entries": {
                          "type": "integer"
                        },
                        "unresolved_source_cents": {
                          "type": [
                            "integer",
                            "string"
                          ],
                          "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                        },
                        "accounting_adjustment_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",
                          "description": "Nominal wait in days. Fixed half-month windows govern eligibility, including short February; this is not an exact rolling hold."
                        },
                        "payout_window_policy": {
                          "type": "string"
                        },
                        "hold_is_approximate": {
                          "type": "boolean"
                        },
                        "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."
                    },
                    "payoutForecast": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "const": "payout-period-forecast-v1"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "available": {
                          "type": "boolean"
                        },
                        "processingKnown": {
                          "type": "boolean"
                        },
                        "pendingProcessingCount": {
                          "type": "integer"
                        },
                        "salesCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "salesFeeCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "earningsBeforeUsageCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "marketingEmailCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "redemptionCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "minimumCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "serviceCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "knownProcessingCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "processingCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "totalNonSaleCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "netBeforePayoutFeesCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "totalDeductionsBeforePayoutFeeCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "amountDueCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "minimumBasis": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "readyToSend": {
                          "const": false
                        },
                        "period_start": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "period_end": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "runDate": {
                          "type": "string",
                          "format": "date"
                        },
                        "charges": {
                          "type": "object",
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "period_start": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "period_end": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "marketing_email_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "redemption_overage_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_adjustment_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "developer_service_fee_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "provider_processing_fees_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "non_sale_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_qualifying_basis": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        },
                        "feePreview": {
                          "type": "object",
                          "properties": {
                            "basis": {
                              "const": "period_forecast"
                            },
                            "projected": {
                              "type": "boolean"
                            },
                            "forecastOnly": {
                              "type": "boolean"
                            },
                            "status": {
                              "type": "string"
                            },
                            "grossCents": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "netCents": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "feeCents": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "currency": {
                              "type": "string"
                            },
                            "provider": {
                              "type": "string"
                            },
                            "country": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "businessCountry": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "payoutCurrency": {
                              "type": "string"
                            },
                            "message": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    },
                    "payoutFeePreview": {
                      "type": "object",
                      "properties": {
                        "enabled": {
                          "type": "boolean"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "waiting",
                            "setup_required",
                            "unavailable",
                            "prepared",
                            "calculated",
                            "estimated"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "currency": {
                          "const": "usd"
                        },
                        "provider": {
                          "type": "string",
                          "enum": [
                            "stripe",
                            "paypal"
                          ]
                        },
                        "country": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "businessCountry": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "payoutCurrency": {
                          "type": "string"
                        },
                        "estimated": {
                          "type": "boolean"
                        },
                        "projected": {
                          "type": "boolean"
                        },
                        "basis": {
                          "type": "string"
                        },
                        "runDate": {
                          "type": "string"
                        },
                        "eligibleAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "transferIntentId": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 1
                            },
                            {
                              "type": "string",
                              "pattern": "^[1-9][0-9]*$"
                            }
                          ]
                        },
                        "grossCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "billingOffsetCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "adjustmentCents": {
                          "type": "integer"
                        },
                        "roundingCarryCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "feeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "netCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "transferFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "crossBorderFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "settlementFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "feeComponents": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "kind": {
                                "type": "string"
                              },
                              "basis": {
                                "type": "string"
                              },
                              "amountCents": {
                                "type": "integer",
                                "minimum": 0
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "conversionFeeCents": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "recipientConversionIncluded": {
                          "type": "boolean"
                        },
                        "monthlyFeePeriod": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "localNetMinor": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "exchangeRate": {
                          "type": "string"
                        },
                        "totalDeveloperFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "netUsdEquivalentCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "fxFeeTreatment": {
                          "type": "string"
                        },
                        "fxQuoteExpiresAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "fxSettled": {
                          "type": "boolean"
                        },
                        "crossBorderEstimated": {
                          "type": "boolean"
                        },
                        "crossBorderEstimateBasisPoints": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "actualFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "differenceCents": {
                          "type": "integer"
                        },
                        "feeReconciled": {
                          "type": "boolean"
                        },
                        "reconciliationStatus": {
                          "type": "string"
                        },
                        "feeDisclosure": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "calculation": {
                          "type": "string"
                        },
                        "period_start": {
                          "type": "string"
                        },
                        "period_end": {
                          "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/transferIntentService.js",
          "services/externalPartnerSalesReportingService.js",
          "services/payoutPeriodForecastService.js",
          "services/actualProcessingFeeService.js",
          "services/developerPayoutPreviewService.js",
          "services/developerStripeLocalPayoutService.js",
          "services/developerPayoutUpfrontRates.js",
          "services/developerPayoutFeeDisclosure.js"
        ]
      }
    },
    "/api/developer/earnings/summary-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/summary-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/summary-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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 Eastern calendar 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": "See the linked operation reference for the response contract.",
            "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",
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "period_start": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "period_end": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "marketing_email_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "redemption_overage_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_adjustment_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "developer_service_fee_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "provider_processing_fees_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "non_sale_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_qualifying_basis": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "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": "AccountSession",
        "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": [
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/earnings/transactions-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/transactions-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/transactions-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "INVALID_ALLOCATION_STATE",
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/earnings/transfers": {
      "get": {
        "summary": "GET /api/developer/settlements/transfers",
        "description": "Active compatibility alias of GET /api/developer/settlements/transfers. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/transferIntentService.js"
        ]
      }
    },
    "/api/developer/earnings/transfers/{id}": {
      "get": {
        "summary": "GET /api/developer/settlements/transfers/{id}",
        "description": "Active compatibility alias of GET /api/developer/settlements/transfers/{id}. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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/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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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/ai/generate-banner": {
      "post": {
        "summary": "POST /api/developer/marketing/ai/generate-banner",
        "description": "Active compatibility alias of POST /api/developer/marketing/ai/generate-banner. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-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/email-marketing/ai/generate-draft": {
      "post": {
        "summary": "POST /api/developer/marketing/ai/generate-draft",
        "description": "Active compatibility alias of POST /api/developer/marketing/ai/generate-draft. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-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/email-marketing/ai/generate-preview-text": {
      "post": {
        "summary": "POST /api/developer/marketing/ai/generate-preview-text",
        "description": "Active compatibility alias of POST /api/developer/marketing/ai/generate-preview-text. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-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/email-marketing/ai/generate-scheduled-deal-draft": {
      "post": {
        "summary": "POST /api/developer/marketing/ai/generate-scheduled-deal-draft",
        "description": "Active compatibility alias of POST /api/developer/marketing/ai/generate-scheduled-deal-draft. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-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/email-marketing/ai/generate-subjects": {
      "post": {
        "summary": "POST /api/developer/marketing/ai/generate-subjects",
        "description": "Active compatibility alias of POST /api/developer/marketing/ai/generate-subjects. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-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/email-marketing/ai/rewrite": {
      "post": {
        "summary": "POST /api/developer/marketing/ai/rewrite",
        "description": "Active compatibility alias of POST /api/developer/marketing/ai/rewrite. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-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/email-marketing/audience/estimate": {
      "post": {
        "summary": "POST /api/developer/marketing/audience/estimate",
        "description": "Active compatibility alias of POST /api/developer/marketing/audience/estimate. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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
                          }
                        },
                        "productMatch": {
                          "type": "string",
                          "enum": [
                            "any",
                            "all"
                          ]
                        },
                        "excludeCampaignIds": {
                          "type": "array",
                          "maxItems": 50,
                          "items": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                        },
                        "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
                          }
                        },
                        "productMatch": {
                          "type": "string",
                          "enum": [
                            "any",
                            "all"
                          ]
                        },
                        "excludeCampaignIds": {
                          "type": "array",
                          "maxItems": 50,
                          "items": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                        },
                        "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": "AccountSession",
        "x-access-scope": "marketing.view and assigned-product audience/segment access in the effective 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-error-codes": [
          "MARKETING_CAMPAIGN_EXCLUSION_INVALID",
          "MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE",
          "MARKETING_CAMPAIGN_SELF_EXCLUSION"
        ],
        "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
                        }
                      },
                      "productMatch": {
                        "type": "string",
                        "enum": [
                          "any",
                          "all"
                        ]
                      },
                      "excludeCampaignIds": {
                        "type": "array",
                        "maxItems": 50,
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                      },
                      "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/email-marketing/automation/audit-events": {
      "get": {
        "summary": "Same contract as /api/developer/marketing/automation/audit-events",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "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": "HTTP 200: auditEvents.",
            "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 session token",
        "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.",
        "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/email-marketing/automation/process": {
      "post": {
        "summary": "Same contract as /api/developer/marketing/automation/process",
        "description": "Processes real eligible queued work for the workspace. Do not use as a health check.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: processed, deliveryUnknown, usageReconciled, sent, skipped, failed, deferred.",
            "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 session token",
        "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.",
        "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/email-marketing/automation/queue": {
      "get": {
        "summary": "Same contract as /api/developer/marketing/automation/queue",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "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": "HTTP 200: queue.",
            "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 session token",
        "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.",
        "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/email-marketing/automation/settings": {
      "get": {
        "summary": "Same contract as /api/developer/marketing/automation/settings",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: settings.",
            "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 session token",
        "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/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js"
        ]
      },
      "patch": {
        "summary": "Same contract as /api/developer/marketing/automation/settings",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: settings.",
            "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 session token",
        "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.",
        "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/email-marketing/automation/signals": {
      "get": {
        "summary": "Same contract as /api/developer/marketing/automation/signals",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "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": "HTTP 200: signals, windows.",
            "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 session token",
        "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.",
        "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/email-marketing/automation/signals/test": {
      "post": {
        "summary": "Same contract as /api/developer/marketing/automation/signals/test",
        "description": "This is not a dry-run endpoint: a signal can queue eligible workflow work. Current permission, consent and suppression rules still apply.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [],
        "responses": {
          "201": {
            "description": "HTTP 201: signal, queued.",
            "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 session token",
        "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.",
        "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/email-marketing/automation/suppression-rules": {
      "get": {
        "summary": "Same contract as /api/developer/marketing/automation/suppression-rules",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "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": "HTTP 200: rules.",
            "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 session token",
        "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.",
        "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/email-marketing/automation/workflows": {
      "get": {
        "summary": "Same contract as /api/developer/marketing/automation/workflows",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "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": "HTTP 200: workflows.",
            "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 session token",
        "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.",
        "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": "Same contract as /api/developer/marketing/automation/workflows",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [],
        "responses": {
          "201": {
            "description": "HTTP 201: workflow.",
            "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 session token",
        "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.",
        "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/email-marketing/automation/workflows/{workflowId}": {
      "patch": {
        "summary": "Same contract as /api/developer/marketing/automation/workflows/{workflowId}",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [
          {
            "name": "workflowId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: workflow.",
            "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 session token",
        "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.",
        "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/email-marketing/automation/workflows/{workflowId}/suppression-rules": {
      "post": {
        "summary": "Same contract as /api/developer/marketing/automation/workflows/{workflowId}/suppression-rules",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [
          {
            "name": "workflowId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "HTTP 201: rule.",
            "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 session token",
        "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.",
        "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/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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending. 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
                                }
                              },
                              "productMatch": {
                                "type": "string",
                                "enum": [
                                  "any",
                                  "all"
                                ]
                              },
                              "excludeCampaignIds": {
                                "type": "array",
                                "maxItems": 50,
                                "items": {
                                  "type": "integer",
                                  "minimum": 1
                                },
                                "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                              },
                              "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"
                              },
                              "costCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "costBasis": {
                                "const": "current_policy_estimate"
                              },
                              "emailsSentCount": {
                                "type": "integer"
                              },
                              "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
                          },
                          "audienceEstimateStatus": {
                            "type": "string",
                            "enum": [
                              "ready",
                              "unavailable"
                            ]
                          }
                        },
                        "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 session token",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      },
      "post": {
        "summary": "Create campaign draft.",
        "description": "Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending. 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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                        },
                        "audienceEstimateStatus": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "unavailable"
                          ]
                        }
                      },
                      "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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 session token",
        "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-error-codes": [
          "MARKETING_CAMPAIGN_EXCLUSION_INVALID",
          "MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE",
          "MARKETING_CAMPAIGN_SELF_EXCLUSION"
        ],
        "x-source-files": [
          "routes/developerMarketingRoutes.js",
          "services/marketingCampaignService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "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
                        }
                      },
                      "productMatch": {
                        "type": "string",
                        "enum": [
                          "any",
                          "all"
                        ]
                      },
                      "excludeCampaignIds": {
                        "type": "array",
                        "maxItems": 50,
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                      },
                      "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}": {
      "delete": {
        "summary": "DELETE /api/developer/marketing/campaigns/{campaignId}",
        "description": "Active compatibility alias of DELETE /api/developer/marketing/campaigns/{campaignId}. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      },
      "get": {
        "summary": "GET /api/developer/marketing/campaigns/{campaignId}",
        "description": "Active compatibility alias of GET /api/developer/marketing/campaigns/{campaignId}. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                        },
                        "audienceEstimateStatus": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "unavailable"
                          ]
                        }
                      },
                      "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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": "AccountSession",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      },
      "patch": {
        "summary": "Update campaign.",
        "description": "Only draft or scheduled content is editable; sent content is not rewritten. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending. 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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                        },
                        "audienceEstimateStatus": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "unavailable"
                          ]
                        }
                      },
                      "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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 session token",
        "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": [
          "MARKETING_CAMPAIGN_EXCLUSION_INVALID",
          "MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE",
          "MARKETING_CAMPAIGN_SELF_EXCLUSION",
          "CAMPAIGN_NOT_EDITABLE"
        ],
        "x-source-files": [
          "routes/developerMarketingRoutes.js",
          "services/marketingCampaignService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "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
                        }
                      },
                      "productMatch": {
                        "type": "string",
                        "enum": [
                          "any",
                          "all"
                        ]
                      },
                      "excludeCampaignIds": {
                        "type": "array",
                        "maxItems": 50,
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                      },
                      "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}/cancel": {
      "post": {
        "summary": "POST /api/developer/marketing/campaigns/{campaignId}/cancel",
        "description": "Active compatibility alias of POST /api/developer/marketing/campaigns/{campaignId}/cancel. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                        },
                        "audienceEstimateStatus": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "unavailable"
                          ]
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "AccountSession",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/api/developer/email-marketing/campaigns/{campaignId}/cost-preview": {
      "get": {
        "summary": "Use the supported compatibility mount for the same cost preview",
        "description": "Requires marketing.view and assigned-product access to the campaign. Estimates the eligible current audience against the planned Eastern billing month, including existing accepted and reserved usage. No provider message or payment is sent, but monthly accounting counters can be initialized; this is not a zero-side-effect health probe. A preview is not a final invoice or a reservation. Billing, chosen budgets and suppression are checked again at dispatch. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "scheduledAt",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "required": false,
            "description": "Optional planned date within the next year."
          },
          {
            "name": "deliveryTimezone",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "required": false,
            "description": "IANA timezone for a planned local date; defaults to UTC."
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: enabled, monthlyLimitCents, monthStart, monthEnd, acceptedQuantity, reservedQuantity, usedCents, committedCents, remainingCents, includedQuantity, rateCentsPer1000, nearLimit, platformPlanningQuantity, platformCommittedQuantity, platformCapacityWarning, platformLimitEnforced, platformRemainingQuantity, canManageLimit, canReviewPlatformCapacity, recipientCount, additionalCents, projectedCents, withinLimit.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "monthlyLimitCents": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "minimum": 0,
                      "description": "Null means no developer spending limit, not free sending."
                    },
                    "monthStart": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "monthEnd": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "acceptedQuantity": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "reservedQuantity": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "usedCents": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "committedCents": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "remainingCents": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "minimum": 0
                    },
                    "includedQuantity": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "rateCentsPer1000": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "nearLimit": {
                      "type": "boolean"
                    },
                    "platformPlanningQuantity": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "platformCommittedQuantity": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "platformCapacityWarning": {
                      "type": "boolean"
                    },
                    "platformLimitEnforced": {
                      "type": "boolean"
                    },
                    "platformRemainingQuantity": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "canManageLimit": {
                      "type": "boolean"
                    },
                    "canReviewPlatformCapacity": {
                      "type": "boolean"
                    },
                    "recipientCount": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "additionalCents": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "projectedCents": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "withinLimit": {
                      "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 session token",
        "x-access-scope": "marketing.view and assigned-product campaign/audience access.",
        "x-request-fields": [
          "query scheduledAt: string. Optional planned date within the next year.",
          "query deliveryTimezone: string. IANA timezone for a planned local date; defaults to UTC."
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.",
        "security": [
          {
            "AccountSession": []
          }
        ],
        "x-contract-coverage": "Reviewed 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_COST_DATE_INVALID"
        ],
        "x-source-files": [
          "routes/developerMarketingRoutes.js",
          "services/marketingCampaignService.js",
          "services/marketingSpendControlService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/api/developer/email-marketing/campaigns/{campaignId}/duplicate": {
      "post": {
        "summary": "POST /api/developer/marketing/campaigns/{campaignId}/duplicate",
        "description": "Active compatibility alias of POST /api/developer/marketing/campaigns/{campaignId}/duplicate. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "See the linked operation reference for the response contract.",
            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                        },
                        "audienceEstimateStatus": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "unavailable"
                          ]
                        }
                      },
                      "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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": "AccountSession",
        "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_CAMPAIGN_EXCLUSION_INVALID",
          "MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE",
          "MARKETING_CAMPAIGN_SELF_EXCLUSION"
        ],
        "x-source-files": [
          "routes/developerMarketingRoutes.js",
          "services/marketingCampaignService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/api/developer/email-marketing/campaigns/{campaignId}/name": {
      "patch": {
        "summary": "PATCH /api/developer/marketing/campaigns/{campaignId}/name",
        "description": "Active compatibility alias of PATCH /api/developer/marketing/campaigns/{campaignId}/name. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                        },
                        "audienceEstimateStatus": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "unavailable"
                          ]
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/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": "AccountSession",
        "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-source-files": [
          "routes/developerMarketingRoutes.js",
          "services/marketingCampaignService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/developer/email-marketing/campaigns/{campaignId}/preview": {
      "post": {
        "summary": "POST /api/developer/marketing/campaigns/{campaignId}/preview",
        "description": "Active compatibility alias of POST /api/developer/marketing/campaigns/{campaignId}/preview. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/api/developer/email-marketing/campaigns/{campaignId}/recipients": {
      "get": {
        "summary": "GET /api/developer/marketing/campaigns/{campaignId}/recipients",
        "description": "Active compatibility alias of GET /api/developer/marketing/campaigns/{campaignId}/recipients. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/api/developer/email-marketing/campaigns/{campaignId}/report": {
      "get": {
        "summary": "GET /api/developer/marketing/campaigns/{campaignId}/report",
        "description": "Active compatibility alias of GET /api/developer/marketing/campaigns/{campaignId}/report. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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"
                    },
                    "costCents": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "costBasis": {
                      "const": "current_policy_estimate"
                    },
                    "emailsSentCount": {
                      "type": "integer"
                    },
                    "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": "AccountSession",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/api/developer/email-marketing/campaigns/{campaignId}/resume-send": {
      "post": {
        "summary": "POST /api/developer/marketing/campaigns/{campaignId}/resume-send",
        "description": "Active compatibility alias of POST /api/developer/marketing/campaigns/{campaignId}/resume-send. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. Resume remaining work, not a new campaign or resend of accepted recipients. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. A developer budget is optional and unlimited by default. Campaigns and automation share accepted and reserved usage in the planned Eastern month. Paid sends require a verified payment method; unpaid live bills and verification failures can pause marketing, including included sends. A platform planning warning alone is not a cap. Uncertain sends retain their reservation and must be reviewed rather than blindly resent. These holds do not revoke licenses or downloads. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                        },
                        "audienceEstimateStatus": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "unavailable"
                          ]
                        }
                      },
                      "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"
                }
              }
            }
          },
          "402": {
            "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "AccountSession",
        "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_CAMPAIGN_EXCLUSION_INVALID",
          "MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE",
          "MARKETING_CAMPAIGN_SELF_EXCLUSION",
          "MARKETING_SPEND_LIMIT_REACHED",
          "MARKETING_PLATFORM_LIMIT_REACHED",
          "MARKETING_DELIVERY_UNCONFIRMED",
          "DEVELOPER_COST_PAYMENT_METHOD_REQUIRED",
          "DEVELOPER_COST_BILLING_RESTRICTED",
          "DEVELOPER_COST_BILLING_UNAVAILABLE",
          "DEVELOPER_COST_FUNDING_UNAVAILABLE",
          "CAMPAIGN_NOT_SENDING"
        ],
        "x-source-files": [
          "routes/developerMarketingRoutes.js",
          "services/marketingCampaignService.js",
          "services/marketingSpendControlService.js",
          "services/developerBillingGateService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/api/developer/email-marketing/campaigns/{campaignId}/retry-failed": {
      "post": {
        "summary": "POST /api/developer/marketing/campaigns/{campaignId}/retry-failed",
        "description": "Active compatibility alias of POST /api/developer/marketing/campaigns/{campaignId}/retry-failed. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scope": {
                    "type": "string",
                    "enum": [
                      "safe",
                      "uncertain"
                    ]
                  },
                  "confirmUncertain": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/developer/email-marketing/campaigns/{campaignId}/retry-summary": {
      "get": {
        "summary": "GET /api/developer/marketing/campaigns/{campaignId}/retry-summary",
        "description": "Active compatibility alias of GET /api/developer/marketing/campaigns/{campaignId}/retry-summary. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/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. A developer budget is optional and unlimited by default. Campaigns and automation share accepted and reserved usage in the planned Eastern month. Paid sends require a verified payment method; unpaid live bills and verification failures can pause marketing, including included sends. A platform planning warning alone is not a cap. Uncertain sends retain their reservation and must be reviewed rather than blindly resent. These holds do not revoke licenses or downloads. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending. 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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                        },
                        "audienceEstimateStatus": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "unavailable"
                          ]
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "402": {
            "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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_SPEND_LIMIT_REACHED",
          "MARKETING_PLATFORM_LIMIT_REACHED",
          "MARKETING_DELIVERY_UNCONFIRMED",
          "DEVELOPER_COST_PAYMENT_METHOD_REQUIRED",
          "DEVELOPER_COST_BILLING_RESTRICTED",
          "DEVELOPER_COST_BILLING_UNAVAILABLE",
          "DEVELOPER_COST_FUNDING_UNAVAILABLE",
          "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",
          "services/marketingSpendControlService.js",
          "services/developerBillingGateService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "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. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. A developer budget is optional and unlimited by default. Campaigns and automation share accepted and reserved usage in the planned Eastern month. Paid sends require a verified payment method; unpaid live bills and verification failures can pause marketing, including included sends. A platform planning warning alone is not a cap. Uncertain sends retain their reservation and must be reviewed rather than blindly resent. These holds do not revoke licenses or downloads. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending. 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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                        },
                        "audienceEstimateStatus": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "unavailable"
                          ]
                        }
                      },
                      "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"
                }
              }
            }
          },
          "402": {
            "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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_CAMPAIGN_EXCLUSION_INVALID",
          "MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE",
          "MARKETING_CAMPAIGN_SELF_EXCLUSION",
          "MARKETING_SPEND_LIMIT_REACHED",
          "MARKETING_PLATFORM_LIMIT_REACHED",
          "MARKETING_DELIVERY_UNCONFIRMED",
          "DEVELOPER_COST_PAYMENT_METHOD_REQUIRED",
          "DEVELOPER_COST_BILLING_RESTRICTED",
          "DEVELOPER_COST_BILLING_UNAVAILABLE",
          "DEVELOPER_COST_FUNDING_UNAVAILABLE",
          "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",
          "services/marketingSpendControlService.js",
          "services/developerBillingGateService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending. 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 session token",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "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/campaigns/latest/report": {
      "get": {
        "summary": "GET /api/developer/marketing/campaigns/latest/report",
        "description": "Active compatibility alias of GET /api/developer/marketing/campaigns/latest/report. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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"
                    },
                    "costCents": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "costBasis": {
                      "const": "current_policy_estimate"
                    },
                    "emailsSentCount": {
                      "type": "integer"
                    },
                    "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": "AccountSession",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/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 session token",
        "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/{id}/consent": {
      "patch": {
        "summary": "PATCH /api/developer/marketing/contacts/{id}/consent",
        "description": "Active compatibility alias of PATCH /api/developer/marketing/contacts/{id}/consent. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-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/email-marketing/contacts/{id}/suppress": {
      "patch": {
        "summary": "PATCH /api/developer/marketing/contacts/{id}/suppress",
        "description": "Active compatibility alias of PATCH /api/developer/marketing/contacts/{id}/suppress. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-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/email-marketing/contacts/bulk-suppress": {
      "patch": {
        "summary": "PATCH /api/developer/marketing/contacts/bulk-suppress",
        "description": "Active compatibility alias of PATCH /api/developer/marketing/contacts/bulk-suppress. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-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/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 session token",
        "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/demo.csv": {
      "get": {
        "summary": "GET /api/developer/marketing/contacts/import/demo.csv",
        "description": "Active compatibility alias of GET /api/developer/marketing/contacts/import/demo.csv. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/developerMarketingRoutes.js",
          "services/marketingCampaignService.js"
        ]
      }
    },
    "/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 session token",
        "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/growth-flows": {
      "get": {
        "summary": "Same contract as /api/developer/marketing/growth-flows",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "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": "HTTP 200: flows, templates, queueSnapshotAt.",
            "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.",
                            "properties": {
                              "includeFreeAcquisitions": {
                                "type": "boolean"
                              }
                            }
                          },
                          "type": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "audienceId": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "productId": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "includeFreeAcquisitions": {
                            "type": "boolean",
                            "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                          },
                          "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"
                              },
                              "type": {
                                "type": "string"
                              },
                              "purchaseRewardOfferId": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "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 session token",
        "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.",
        "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": "Same contract as /api/developer/marketing/growth-flows",
        "description": "includeFreeAcquisitions must be a JSON boolean at top level or in metadata; a supplied top-level boolean takes precedence. Supported access flows include cross_sell_upsell, review_request, product_onboarding and product_update. Cross-sell and configured review/onboarding flows can respond to qualifying access events. Product-update audience eligibility does not make a grant a release trigger: a product-update event or deliberately reviewed history enrollment is still required. Saving the setting alone does not replay history or send messages. Explicit false retains paid-acquisition proof. A purchase-reward flow needs explicit true plus a program permitting free items; a conflicting program is rejected. Active recipient-owned access, popup verification, current state/expiry, enrollment eligibility and suppression checks remain required. Free access and reward coupons do not become paid orders. Retry of the same acquisition/program reuses its reward.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [],
        "responses": {
          "201": {
            "description": "HTTP 201: flow.",
            "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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.",
        "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",
          "includeFreeAcquisitions: boolean. For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program.",
          "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-error-codes": [
          "GROWTH_FLOW_ACQUISITION_SETTING_INVALID",
          "GROWTH_FLOW_REWARD_FREE_ACCESS_EXCLUDED"
        ],
        "x-source-files": [
          "routes/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js",
          "services/growthFlowAcquisitionPolicy.js",
          "services/growthFlowPurchaseRewardService.js"
        ],
        "x-source-revision": "ed7e5def3d871d9267d7cfd4ff1b76e9a162d4c8",
        "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.",
                    "properties": {
                      "includeFreeAcquisitions": {
                        "type": "boolean"
                      }
                    }
                  },
                  "type": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "audienceId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "productId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "includeFreeAcquisitions": {
                    "type": "boolean",
                    "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                  },
                  "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"
                      },
                      "type": {
                        "type": "string"
                      },
                      "purchaseRewardOfferId": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "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/email-marketing/growth-flows/{flowId}": {
      "get": {
        "summary": "Same contract as /api/developer/marketing/growth-flows/{flowId}",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [
          {
            "name": "flowId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: flow.",
            "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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "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/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js"
        ]
      },
      "patch": {
        "summary": "Same contract as /api/developer/marketing/growth-flows/{flowId}",
        "description": "includeFreeAcquisitions must be a JSON boolean at top level or in metadata; a supplied top-level boolean takes precedence. Supported access flows include cross_sell_upsell, review_request, product_onboarding and product_update. Cross-sell and configured review/onboarding flows can respond to qualifying access events. Product-update audience eligibility does not make a grant a release trigger: a product-update event or deliberately reviewed history enrollment is still required. Saving the setting alone does not replay history or send messages. Explicit false retains paid-acquisition proof. A purchase-reward flow needs explicit true plus a program permitting free items; a conflicting program is rejected. Active recipient-owned access, popup verification, current state/expiry, enrollment eligibility and suppression checks remain required. Free access and reward coupons do not become paid orders. Retry of the same acquisition/program reuses its reward.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [
          {
            "name": "flowId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: flow.",
            "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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.",
        "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",
          "includeFreeAcquisitions: boolean. For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program.",
          "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-error-codes": [
          "GROWTH_FLOW_ACQUISITION_SETTING_INVALID",
          "GROWTH_FLOW_REWARD_FREE_ACCESS_EXCLUDED"
        ],
        "x-source-files": [
          "routes/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js",
          "services/growthFlowAcquisitionPolicy.js",
          "services/growthFlowPurchaseRewardService.js"
        ],
        "x-source-revision": "ed7e5def3d871d9267d7cfd4ff1b76e9a162d4c8",
        "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.",
                    "properties": {
                      "includeFreeAcquisitions": {
                        "type": "boolean"
                      }
                    }
                  },
                  "type": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "audienceId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "productId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "includeFreeAcquisitions": {
                    "type": "boolean",
                    "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                  },
                  "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"
                      },
                      "type": {
                        "type": "string"
                      },
                      "purchaseRewardOfferId": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "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/email-marketing/growth-flows/{flowId}/activate": {
      "post": {
        "summary": "Same contract as /api/developer/marketing/growth-flows/{flowId}/activate",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [
          {
            "name": "flowId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: flow.",
            "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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "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/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js"
        ]
      }
    },
    "/api/developer/email-marketing/growth-flows/{flowId}/archive": {
      "post": {
        "summary": "Same contract as /api/developer/marketing/growth-flows/{flowId}/archive",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [
          {
            "name": "flowId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: flow.",
            "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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "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/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js"
        ]
      }
    },
    "/api/developer/email-marketing/growth-flows/{flowId}/duplicate": {
      "post": {
        "summary": "Same contract as /api/developer/marketing/growth-flows/{flowId}/duplicate",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [
          {
            "name": "flowId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "HTTP 201: flow.",
            "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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "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/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js"
        ]
      }
    },
    "/api/developer/email-marketing/growth-flows/{flowId}/enroll-previous": {
      "post": {
        "summary": "Schedule historical eligible customers for an active growth flow",
        "description": "Requires an active flow and enabled automation. A new job returns started:true, jobId and eligibleRecipients. The same pending configuration returns started:false, alreadyRunning:true and the existing jobId, without a fresh eligible count. Changed pending configuration can supersede earlier fanout. No eligible recipients returns started:false, eligibleRecipients:0 and no jobId. Messages wait at least 24 hours; recipient eligibility is checked again before sending. This is a queue mutation, not an immediate-send or harmless preview.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [
          {
            "name": "flowId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: review the response schema below.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "started": {
                          "const": true
                        },
                        "jobId": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 1
                            },
                            {
                              "type": "string",
                              "pattern": "^[1-9][0-9]*$"
                            }
                          ]
                        },
                        "eligibleRecipients": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "minimumWaitHours": {
                          "const": 24
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "started",
                        "jobId",
                        "eligibleRecipients",
                        "minimumWaitHours"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "started": {
                          "const": false
                        },
                        "alreadyRunning": {
                          "const": true
                        },
                        "jobId": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 1
                            },
                            {
                              "type": "string",
                              "pattern": "^[1-9][0-9]*$"
                            }
                          ]
                        },
                        "minimumWaitHours": {
                          "const": 24
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "started",
                        "alreadyRunning",
                        "jobId",
                        "minimumWaitHours"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "started": {
                          "const": false
                        },
                        "eligibleRecipients": {
                          "const": 0
                        },
                        "minimumWaitHours": {
                          "const": 24
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "started",
                        "eligibleRecipients",
                        "minimumWaitHours"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "marketing.manage and all-products workspace scope. Current audience eligibility and suppression are rechecked.",
        "x-request-fields": [
          "scope: \"all_previous\" (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/growthFlowEligibilityService.js",
          "services/emailGrowthFlowService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scope": {
                    "const": "all_previous"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "scope"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/email-marketing/growth-flows/{flowId}/history-preview": {
      "get": {
        "summary": "Preview all previous eligible recipients without enrolling them",
        "description": "A count is a current eligibility estimate, not a delivery promise. It shares the enrollment query and reflects current product access, audience, flow configuration, prior work and marketing restrictions. flowId may be a decimal string. canEnroll is not proof that the master automation setting is enabled.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [
          {
            "name": "flowId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: flowId, name, type, status, eligibleRecipients, reason, minimumWaitHours, scope, canEnroll.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "flowId": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "minimum": 1
                        },
                        {
                          "type": "string",
                          "pattern": "^[1-9][0-9]*$"
                        }
                      ],
                      "description": "Database workflow identifier; accept its decimal string form without treating it as a UUID."
                    },
                    "name": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "eligibleRecipients": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "reason": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "minimumWaitHours": {
                      "const": 24
                    },
                    "scope": {
                      "const": "all_previous"
                    },
                    "canEnroll": {
                      "type": "boolean",
                      "description": "Hint from active workflow, configuration and eligible count. Enrollment separately requires automation to be enabled and rechecks eligibility."
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "marketing.manage and all-products workspace scope. Current audience eligibility and suppression are rechecked.",
        "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/growthFlowEligibilityService.js",
          "services/emailGrowthFlowService.js"
        ]
      }
    },
    "/api/developer/email-marketing/growth-flows/{flowId}/pause": {
      "post": {
        "summary": "Same contract as /api/developer/marketing/growth-flows/{flowId}/pause",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [
          {
            "name": "flowId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: flow.",
            "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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "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/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js"
        ]
      }
    },
    "/api/developer/email-marketing/growth-flows/{flowId}/preview": {
      "get": {
        "summary": "Same contract as /api/developer/marketing/growth-flows/{flowId}/preview",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [
          {
            "name": "flowId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: flow.",
            "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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "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/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js"
        ]
      }
    },
    "/api/developer/email-marketing/growth-flows/{flowId}/recipients": {
      "get": {
        "summary": "Same contract as /api/developer/marketing/growth-flows/{flowId}/recipients",
        "description": "For status=queued, inspect sendHoldCode, failureReason and nextRetryAt separately from scheduledFor. A funding hold keeps the planned date and uses a separate retry deadline, normally set 15 minutes after the deferred attempt. Worker selection and claim both respect that deadline. Once funding and spend checks succeed, held work can retry automatically; provider availability, active flow, consent, ownership and queue eligibility still apply. Do not reset the flow or use Retry unconfirmed for an ordinary funding pause. The row may remain queued while sending is paused; a past scheduledFor is not proof of a send.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "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",
                            "description": "Planned send date. For a queued funding hold, preserves not_before when recorded, otherwise scheduled_for; not the next funding-retry time."
                          },
                          "sendHoldCode": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Queued spend/funding hold code, otherwise null. A hold is not provider acceptance or delivery_unknown."
                          },
                          "nextRetryAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time",
                            "description": "Queued funding retry eligibility from spendHoldRetryAt, with a legacy scheduled_for fallback. Otherwise null. Not a guaranteed send 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 session token",
        "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",
          "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/email-marketing/growth-flows/{flowId}/recipients/{queueId}/retry": {
      "post": {
        "summary": "Same contract as /api/developer/marketing/growth-flows/{flowId}/recipients/{queueId}/retry",
        "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": "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"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js"
        ]
      }
    },
    "/api/developer/email-marketing/growth-flows/{flowId}/recipients/{queueId}/retry-unconfirmed": {
      "post": {
        "summary": "Same contract as /api/developer/marketing/growth-flows/{flowId}/recipients/{queueId}/retry-unconfirmed",
        "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 session token",
        "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/email-marketing/growth-flows/{flowId}/recipients/{queueId}/review": {
      "post": {
        "summary": "Same contract as /api/developer/marketing/growth-flows/{flowId}/recipients/{queueId}/review",
        "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": "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"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js"
        ]
      }
    },
    "/api/developer/email-marketing/growth-flows/{flowId}/run": {
      "post": {
        "summary": "Same contract as /api/developer/marketing/growth-flows/{flowId}/run",
        "description": "Launches supported manual audience work. No eligible audience means no permission to send to suppressed contacts.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "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/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js"
        ]
      }
    },
    "/api/developer/email-marketing/growth-flows/{flowId}/test-email": {
      "post": {
        "summary": "Same contract as /api/developer/marketing/growth-flows/{flowId}/test-email",
        "description": "The recipient must be the signed-in developer. Select a valid sequence step; sender/footer readiness still applies.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [
          {
            "name": "flowId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: sent.",
            "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 session token",
        "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.",
        "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/email-marketing/growth-flows/email-preview": {
      "post": {
        "summary": "Render a branded primary or reward email without sending",
        "description": "Uses the maintained delivery renderer and current branding. headerEnabled:false removes the header; headerLogo accepts a supported HTTP(S) URL or an empty value. Cross-sell trigger products and recommendations are separate. Preview is not an email send, inbox-rendering guarantee, consent change or recipient enrollment.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: subject, html, text.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "subject": {
                      "type": "string"
                    },
                    "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"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "marketing.manage and all-products workspace scope. Current audience eligibility and suppression are rechecked.",
        "x-request-fields": [
          "type: string",
          "productId: integer",
          "reward: boolean",
          "email: object",
          "metadata: 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/growthFlowEligibilityService.js",
          "services/emailGrowthFlowService.js"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string"
                  },
                  "productId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "reward": {
                    "type": "boolean"
                  },
                  "email": {
                    "type": "object",
                    "properties": {
                      "subject": {
                        "type": "string"
                      },
                      "body": {
                        "type": "string"
                      },
                      "bodyHtml": {
                        "type": "string"
                      },
                      "emailDesign": {
                        "type": "object",
                        "properties": {
                          "headerEnabled": {
                            "type": "boolean"
                          },
                          "headerLogo": {
                            "type": "string"
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "additionalProperties": true
                  },
                  "metadata": {
                    "type": "object",
                    "properties": {
                      "triggerProductIds": {
                        "type": "array",
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        }
                      },
                      "recommendedProductIds": {
                        "type": "array",
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        }
                      }
                    },
                    "additionalProperties": true
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/developer/email-marketing/growth-flows/promo-options": {
      "get": {
        "summary": "Same contract as /api/developer/marketing/growth-flows/promo-options",
        "description": "Returns static promo codes separately from purchase-reward programs. A selected inactive reward may be included for editing; it is not eligible for new reward issuance.",
        "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": ""
          },
          {
            "name": "selectedRewardId",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "required": false,
            "description": ""
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: promoCodes, purchaseRewards.",
            "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
                      }
                    },
                    "purchaseRewards": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "title": {
                            "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 session token",
        "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.",
        "x-request-fields": [
          "query search: string",
          "query selectedId: integer",
          "query selectedRewardId: 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",
          "services/growthFlowPurchaseRewardService.js"
        ]
      }
    },
    "/api/developer/email-marketing/growth-flows/purchase-rewards": {
      "post": {
        "summary": "Use the supported email-marketing compatibility mount for the same reward helper",
        "description": "Creates an active post_purchase_coupon program for the owned trigger products, not a shared coupon code. Percent is the default discount type and cannot exceed 100; amount is a dollar discount. The helper sets requiredQuantity:1 and order-scoped paid grants. A qualifying paid order can issue a recipient-specific coupon. A cross-sell flow explicitly enabling includeFreeAcquisitions can instead use verified active access if the program allows free items and its quantity rules are satisfied; that grant retains entitlement provenance, not a fabricated order. This request alone does not send email, enroll an audience or issue a coupon. Existing promotion validation and marketing.manage/all-products checks apply.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [],
        "responses": {
          "201": {
            "description": "HTTP 201: offer.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "offer": {
                      "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 session token",
        "x-access-scope": "marketing.manage and all-products workspace scope; identical request and response contract.",
        "x-request-fields": [
          "title: string (required)",
          "productIds: array (required)",
          "discountType: percent | amount",
          "discountValue: number (required)",
          "codePrefix: 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",
          "services/growthFlowPurchaseRewardService.js",
          "services/developerPromotionService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "minLength": 1,
                    "pattern": "\\S"
                  },
                  "productIds": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "minItems": 1
                  },
                  "discountType": {
                    "type": "string",
                    "enum": [
                      "percent",
                      "amount"
                    ]
                  },
                  "discountValue": {
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  "codePrefix": {
                    "type": "string"
                  }
                },
                "required": [
                  "title",
                  "productIds",
                  "discountValue"
                ],
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/developer/email-marketing/growth-flows/summary": {
      "get": {
        "summary": "Same contract as /api/developer/marketing/growth-flows/summary",
        "description": "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.",
        "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": "HTTP 200: flows, templates, rangeDays, range, activeFlows, archivedFlows, archivedActivity, totalFlows, emailsSent, revenue, conversions, queuedNow, sentTotal, failedTotal, unresolvedTotal, queueSnapshotAt, recommendations.",
            "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.",
                            "properties": {
                              "includeFreeAcquisitions": {
                                "type": "boolean"
                              }
                            }
                          },
                          "type": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "audienceId": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "productId": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "includeFreeAcquisitions": {
                            "type": "boolean",
                            "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                          },
                          "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"
                              },
                              "type": {
                                "type": "string"
                              },
                              "purchaseRewardOfferId": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "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 session token",
        "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.",
        "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/email-marketing/growth-flows/templates": {
      "get": {
        "summary": "Same contract as /api/developer/marketing/growth-flows/templates",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: templates.",
            "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 session token",
        "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/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js"
        ]
      }
    },
    "/api/developer/email-marketing/growth-flows/templates/{type}/activate": {
      "post": {
        "summary": "Same contract as /api/developer/marketing/growth-flows/templates/{type}/activate",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [
          {
            "name": "type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: flow, created.",
            "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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "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/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js"
        ]
      }
    },
    "/api/developer/email-marketing/growth-flows/templates/{type}/pause": {
      "post": {
        "summary": "Same contract as /api/developer/marketing/growth-flows/templates/{type}/pause",
        "description": "Active compatibility mount of the same marketing router, with identical operation-specific authorization and state handling. Prefer the canonical /api/developer/marketing route for new integrations; the alias does not bypass marketing.manage, product scope or all-products requirements.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [
          {
            "name": "type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: flow, created.",
            "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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "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/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js"
        ]
      }
    },
    "/api/developer/email-marketing/scheduled-deals/{dealId}/campaign-draft": {
      "post": {
        "summary": "POST /api/developer/marketing/scheduled-deals/{dealId}/campaign-draft",
        "description": "Active compatibility alias of POST /api/developer/marketing/scheduled-deals/{dealId}/campaign-draft. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "dealId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "See the linked operation reference for the response contract.",
            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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": "AccountSession",
        "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-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
                        }
                      },
                      "productMatch": {
                        "type": "string",
                        "enum": [
                          "any",
                          "all"
                        ]
                      },
                      "excludeCampaignIds": {
                        "type": "array",
                        "maxItems": 50,
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                      },
                      "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/email-marketing/segments": {
      "get": {
        "summary": "GET /api/developer/marketing/segments",
        "description": "Active compatibility alias of GET /api/developer/marketing/segments. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary.",
        "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": "See the linked operation reference for the response contract.",
            "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
                                }
                              },
                              "productMatch": {
                                "type": "string",
                                "enum": [
                                  "any",
                                  "all"
                                ]
                              },
                              "excludeCampaignIds": {
                                "type": "array",
                                "maxItems": 50,
                                "items": {
                                  "type": "integer",
                                  "minimum": 1
                                },
                                "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                              },
                              "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
                                    }
                                  },
                                  "productMatch": {
                                    "type": "string",
                                    "enum": [
                                      "any",
                                      "all"
                                    ]
                                  },
                                  "excludeCampaignIds": {
                                    "type": "array",
                                    "maxItems": 50,
                                    "items": {
                                      "type": "integer",
                                      "minimum": 1
                                    },
                                    "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                                  },
                                  "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
                                    }
                                  },
                                  "productMatch": {
                                    "type": "string",
                                    "enum": [
                                      "any",
                                      "all"
                                    ]
                                  },
                                  "excludeCampaignIds": {
                                    "type": "array",
                                    "maxItems": 50,
                                    "items": {
                                      "type": "integer",
                                      "minimum": 1
                                    },
                                    "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                                  },
                                  "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": "AccountSession",
        "x-access-scope": "marketing.view and assigned-product audience/segment access in the effective 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/developerMarketingRoutes.js",
          "services/marketingCampaignService.js"
        ]
      },
      "post": {
        "summary": "POST /api/developer/marketing/segments",
        "description": "Active compatibility alias of POST /api/developer/marketing/segments. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [],
        "responses": {
          "201": {
            "description": "See the linked operation reference for the response contract.",
            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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
                                  }
                                },
                                "productMatch": {
                                  "type": "string",
                                  "enum": [
                                    "any",
                                    "all"
                                  ]
                                },
                                "excludeCampaignIds": {
                                  "type": "array",
                                  "maxItems": 50,
                                  "items": {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                                },
                                "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
                                  }
                                },
                                "productMatch": {
                                  "type": "string",
                                  "enum": [
                                    "any",
                                    "all"
                                  ]
                                },
                                "excludeCampaignIds": {
                                  "type": "array",
                                  "maxItems": 50,
                                  "items": {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                                },
                                "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": "AccountSession",
        "x-access-scope": "marketing.view + marketing.manage and assigned-product audience/segment access in the effective 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-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
                        }
                      },
                      "productMatch": {
                        "type": "string",
                        "enum": [
                          "any",
                          "all"
                        ]
                      },
                      "excludeCampaignIds": {
                        "type": "array",
                        "maxItems": 50,
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                      },
                      "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/email-marketing/segments/{segmentId}": {
      "delete": {
        "summary": "DELETE /api/developer/marketing/segments/{segmentId}",
        "description": "Active compatibility alias of DELETE /api/developer/marketing/segments/{segmentId}. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "segmentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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
                                  }
                                },
                                "productMatch": {
                                  "type": "string",
                                  "enum": [
                                    "any",
                                    "all"
                                  ]
                                },
                                "excludeCampaignIds": {
                                  "type": "array",
                                  "maxItems": 50,
                                  "items": {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                                },
                                "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
                                  }
                                },
                                "productMatch": {
                                  "type": "string",
                                  "enum": [
                                    "any",
                                    "all"
                                  ]
                                },
                                "excludeCampaignIds": {
                                  "type": "array",
                                  "maxItems": 50,
                                  "items": {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                                },
                                "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": "AccountSession",
        "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": "PATCH /api/developer/marketing/segments/{segmentId}",
        "description": "Active compatibility alias of PATCH /api/developer/marketing/segments/{segmentId}. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "segmentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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
                                  }
                                },
                                "productMatch": {
                                  "type": "string",
                                  "enum": [
                                    "any",
                                    "all"
                                  ]
                                },
                                "excludeCampaignIds": {
                                  "type": "array",
                                  "maxItems": 50,
                                  "items": {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                                },
                                "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
                                  }
                                },
                                "productMatch": {
                                  "type": "string",
                                  "enum": [
                                    "any",
                                    "all"
                                  ]
                                },
                                "excludeCampaignIds": {
                                  "type": "array",
                                  "maxItems": 50,
                                  "items": {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                                },
                                "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": "AccountSession",
        "x-access-scope": "marketing.view + marketing.manage and assigned-product audience/segment access in the effective 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-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
                        }
                      },
                      "productMatch": {
                        "type": "string",
                        "enum": [
                          "any",
                          "all"
                        ]
                      },
                      "excludeCampaignIds": {
                        "type": "array",
                        "maxItems": 50,
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                      },
                      "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/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."
                        },
                        "spending": {
                          "type": "object",
                          "properties": {
                            "enabled": {
                              "type": "boolean"
                            },
                            "monthlyLimitCents": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "minimum": 0,
                              "description": "Null means no developer spending limit, not free sending."
                            },
                            "monthStart": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "monthEnd": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "acceptedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "reservedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "usedCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "committedCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "remainingCents": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "minimum": 0
                            },
                            "includedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "rateCentsPer1000": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "nearLimit": {
                              "type": "boolean"
                            },
                            "platformPlanningQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "platformCommittedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "platformCapacityWarning": {
                              "type": "boolean"
                            },
                            "platformLimitEnforced": {
                              "type": "boolean"
                            },
                            "platformRemainingQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "canManageLimit": {
                              "type": "boolean"
                            },
                            "canReviewPlatformCapacity": {
                              "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"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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. Requires marketing.manage and all-products scope. Only the account owner or authorized platform owner can set or clear monthlySpendLimitUsd; other authorized teammates may retain their ordinary sender-setting edits without that field. Budgets are optional, unlimited by default, shared by campaigns and Growth Flows, and not a credit against the Full Store minimum. This setting does not bypass billing readiness, 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."
                        },
                        "spending": {
                          "type": "object",
                          "properties": {
                            "enabled": {
                              "type": "boolean"
                            },
                            "monthlyLimitCents": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "minimum": 0,
                              "description": "Null means no developer spending limit, not free sending."
                            },
                            "monthStart": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "monthEnd": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "acceptedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "reservedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "usedCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "committedCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "remainingCents": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "minimum": 0
                            },
                            "includedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "rateCentsPer1000": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "nearLimit": {
                              "type": "boolean"
                            },
                            "platformPlanningQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "platformCommittedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "platformCapacityWarning": {
                              "type": "boolean"
                            },
                            "platformLimitEnforced": {
                              "type": "boolean"
                            },
                            "platformRemainingQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "canManageLimit": {
                              "type": "boolean"
                            },
                            "canReviewPlatformCapacity": {
                              "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"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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",
          "monthlySpendLimitUsd: string,number,null. USD with up to two decimal places. Omit to preserve, clear with an empty string or null for unlimited, or use 0 for included sends only. Changing this field requires account-owner authority."
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host 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_SPEND_OWNER_REQUIRED",
          "MARKETING_SPEND_LIMIT_INVALID"
        ],
        "x-source-files": [
          "routes/developerMarketingRoutes.js",
          "services/marketingCampaignService.js",
          "services/marketingSpendControlService.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"
                  },
                  "monthlySpendLimitUsd": {
                    "type": [
                      "string",
                      "number",
                      "null"
                    ],
                    "description": "USD with up to two decimal places. Omit to preserve, clear with an empty string or null for unlimited, or use 0 for included sends only. Changing this field requires account-owner authority."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/developer/email-marketing/summary": {
      "get": {
        "summary": "GET /api/developer/marketing/summary",
        "description": "Active compatibility alias of GET /api/developer/marketing/summary. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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."
                        },
                        "spending": {
                          "type": "object",
                          "properties": {
                            "enabled": {
                              "type": "boolean"
                            },
                            "monthlyLimitCents": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "minimum": 0,
                              "description": "Null means no developer spending limit, not free sending."
                            },
                            "monthStart": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "monthEnd": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "acceptedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "reservedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "usedCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "committedCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "remainingCents": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "minimum": 0
                            },
                            "includedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "rateCentsPer1000": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "nearLimit": {
                              "type": "boolean"
                            },
                            "platformPlanningQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "platformCommittedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "platformCapacityWarning": {
                              "type": "boolean"
                            },
                            "platformLimitEnforced": {
                              "type": "boolean"
                            },
                            "platformRemainingQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "canManageLimit": {
                              "type": "boolean"
                            },
                            "canReviewPlatformCapacity": {
                              "type": "boolean"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "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": "AccountSession",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/developerMarketingRoutes.js",
          "services/marketingCampaignService.js"
        ]
      }
    },
    "/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 session token",
        "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": "Current live usage estimates use one shared allowance per Eastern calendar month, including campaigns and automation. total_cents is a current-policy estimate, not a finalized invoice, historical payment or waiver. Campaign reports allocate overage blocks in actual send order instead of giving each campaign a separate allowance. 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"
                    },
                    "costBasis": {
                      "const": "current_policy_estimate"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/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 session token",
        "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",
          "services/marketingBillingUsageReportingService.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 session token",
        "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 session token",
        "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 session token",
        "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/headless": {
      "delete": {
        "summary": "Remove the saved external website connection",
        "description": "The effective selected workspace owns the settings, not the acting teammate. Exact public HTTPS origin and five distinct plain callback paths are required. Saving rotates the private server key and TXT proof, clears verification and requires updating every website replica. GET never returns the saved private key. Deleting disconnects website context; it is not a storefront/domain deletion. DNS verification does not move hosting or provision SSL for your independently hosted site.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/custom-websites"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "200: Inspect the response schema and conditional states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "website": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "storefrontId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "storefrontSlug": {
                          "type": "string"
                        },
                        "origin": {
                          "type": "string"
                        },
                        "verified": {
                          "type": "boolean"
                        },
                        "verifiedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "callbacks": {
                          "type": "object",
                          "properties": {
                            "verification": {
                              "type": "string"
                            },
                            "reset": {
                              "type": "string"
                            },
                            "login": {
                              "type": "string"
                            },
                            "success": {
                              "type": "string"
                            },
                            "cancel": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        },
                        "dns": {
                          "type": "object",
                          "properties": {
                            "type": {
                              "const": "TXT"
                            },
                            "name": {
                              "type": "string"
                            },
                            "value": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    },
                    "defaults": {
                      "type": "object",
                      "properties": {
                        "verification": {
                          "type": "string"
                        },
                        "reset": {
                          "type": "string"
                        },
                        "login": {
                          "type": "string"
                        },
                        "success": {
                          "type": "string"
                        },
                        "cancel": {
                          "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 session token",
        "x-access-scope": "Active developer workspace, domains.view and all-products scope; writes and package downloads also require domains.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/developerHeadlessRoutes.js",
          "services/headlessWebsiteService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      },
      "get": {
        "summary": "Read external website settings",
        "description": "The effective selected workspace owns the settings, not the acting teammate. Exact public HTTPS origin and five distinct plain callback paths are required. Saving rotates the private server key and TXT proof, clears verification and requires updating every website replica. GET never returns the saved private key. Deleting disconnects website context; it is not a storefront/domain deletion. DNS verification does not move hosting or provision SSL for your independently hosted site.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/custom-websites"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "200: Inspect the response schema and conditional states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "website": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "storefrontId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "storefrontSlug": {
                          "type": "string"
                        },
                        "origin": {
                          "type": "string"
                        },
                        "verified": {
                          "type": "boolean"
                        },
                        "verifiedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "callbacks": {
                          "type": "object",
                          "properties": {
                            "verification": {
                              "type": "string"
                            },
                            "reset": {
                              "type": "string"
                            },
                            "login": {
                              "type": "string"
                            },
                            "success": {
                              "type": "string"
                            },
                            "cancel": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        },
                        "dns": {
                          "type": "object",
                          "properties": {
                            "type": {
                              "const": "TXT"
                            },
                            "name": {
                              "type": "string"
                            },
                            "value": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    },
                    "defaults": {
                      "type": "object",
                      "properties": {
                        "verification": {
                          "type": "string"
                        },
                        "reset": {
                          "type": "string"
                        },
                        "login": {
                          "type": "string"
                        },
                        "success": {
                          "type": "string"
                        },
                        "cancel": {
                          "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 session token",
        "x-access-scope": "Active developer workspace, domains.view and all-products scope; writes and package downloads also require domains.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/developerHeadlessRoutes.js",
          "services/headlessWebsiteService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      },
      "put": {
        "summary": "Save external website origin and callbacks; rotate its key",
        "description": "The effective selected workspace owns the settings, not the acting teammate. Exact public HTTPS origin and five distinct plain callback paths are required. Saving rotates the private server key and TXT proof, clears verification and requires updating every website replica. GET never returns the saved private key. Deleting disconnects website context; it is not a storefront/domain deletion. DNS verification does not move hosting or provision SSL for your independently hosted site.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/custom-websites"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "200: Inspect the response schema and conditional states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "website": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "storefrontId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "storefrontSlug": {
                          "type": "string"
                        },
                        "origin": {
                          "type": "string"
                        },
                        "verified": {
                          "type": "boolean"
                        },
                        "verifiedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "callbacks": {
                          "type": "object",
                          "properties": {
                            "verification": {
                              "type": "string"
                            },
                            "reset": {
                              "type": "string"
                            },
                            "login": {
                              "type": "string"
                            },
                            "success": {
                              "type": "string"
                            },
                            "cancel": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        },
                        "dns": {
                          "type": "object",
                          "properties": {
                            "type": {
                              "const": "TXT"
                            },
                            "name": {
                              "type": "string"
                            },
                            "value": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    },
                    "defaults": {
                      "type": "object",
                      "properties": {
                        "verification": {
                          "type": "string"
                        },
                        "reset": {
                          "type": "string"
                        },
                        "login": {
                          "type": "string"
                        },
                        "success": {
                          "type": "string"
                        },
                        "cancel": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    },
                    "serverKey": {
                      "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 session token",
        "x-access-scope": "Active developer workspace, domains.view and all-products scope; writes and package downloads also require domains.manage.",
        "x-request-fields": [
          "origin: string (required)",
          "callbacks: 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/developerHeadlessRoutes.js",
          "services/headlessWebsiteService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string"
                  },
                  "callbacks": {
                    "type": "object",
                    "properties": {
                      "verification": {
                        "type": "string"
                      },
                      "reset": {
                        "type": "string"
                      },
                      "login": {
                        "type": "string"
                      },
                      "success": {
                        "type": "string"
                      },
                      "cancel": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true
                  }
                },
                "additionalProperties": true,
                "required": [
                  "origin"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/headless/package": {
      "get": {
        "summary": "Download a website integration starter",
        "description": "Default integration is astro-node and mode is full_store. External mode downloads are selected through fastspring, gumroad or woocommerce; the general framework cards select Full Store. Invalid combinations return 400. The ZIP is generated without live secrets or customer data. INTEGRATION.json records payment/tax responsibility. Merge routes deliberately; do not overwrite your existing project. Cache-Control: no-store.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/custom-websites"
        },
        "parameters": [
          {
            "name": "integration",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "astro-node",
                "node-express",
                "nextjs",
                "nuxt",
                "sveltekit",
                "php",
                "wordpress",
                "fastspring",
                "gumroad",
                "woocommerce"
              ]
            }
          },
          {
            "name": "mode",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "full_store",
                "external"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200: Inspect the response schema and conditional states.",
            "content": {
              "application/zip": {
                "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 session token",
        "x-access-scope": "Active developer workspace, domains.view and all-products scope; writes and package downloads also require domains.manage.",
        "x-request-fields": [
          "query integration: string",
          "query mode: 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/developerHeadlessRoutes.js",
          "services/headlessWebsiteService.js",
          "services/websiteIntegrationPackageService.js",
          "public/store/modules/developer/integrationCatalog.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/api/developer/headless/verify": {
      "post": {
        "summary": "Verify the current website TXT record",
        "description": "The effective selected workspace owns the settings, not the acting teammate. Exact public HTTPS origin and five distinct plain callback paths are required. Saving rotates the private server key and TXT proof, clears verification and requires updating every website replica. GET never returns the saved private key. Deleting disconnects website context; it is not a storefront/domain deletion. DNS verification does not move hosting or provision SSL for your independently hosted site. Rate limited to ten attempts per minute. A concurrent settings change returns WEBSITE_CHANGED instead of verifying the previous proof.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/custom-websites"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "200: Inspect the response schema and conditional states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "website": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "storefrontId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "storefrontSlug": {
                          "type": "string"
                        },
                        "origin": {
                          "type": "string"
                        },
                        "verified": {
                          "type": "boolean"
                        },
                        "verifiedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "callbacks": {
                          "type": "object",
                          "properties": {
                            "verification": {
                              "type": "string"
                            },
                            "reset": {
                              "type": "string"
                            },
                            "login": {
                              "type": "string"
                            },
                            "success": {
                              "type": "string"
                            },
                            "cancel": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        },
                        "dns": {
                          "type": "object",
                          "properties": {
                            "type": {
                              "const": "TXT"
                            },
                            "name": {
                              "type": "string"
                            },
                            "value": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    },
                    "defaults": {
                      "type": "object",
                      "properties": {
                        "verification": {
                          "type": "string"
                        },
                        "reset": {
                          "type": "string"
                        },
                        "login": {
                          "type": "string"
                        },
                        "success": {
                          "type": "string"
                        },
                        "cancel": {
                          "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"
                }
              }
            }
          },
          "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 session token",
        "x-access-scope": "Active developer workspace, domains.view and all-products scope; writes and package downloads also require domains.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/developerHeadlessRoutes.js",
          "services/headlessWebsiteService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. 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
                          }
                        },
                        "productMatch": {
                          "type": "string",
                          "enum": [
                            "any",
                            "all"
                          ]
                        },
                        "excludeCampaignIds": {
                          "type": "array",
                          "maxItems": 50,
                          "items": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                        },
                        "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
                          }
                        },
                        "productMatch": {
                          "type": "string",
                          "enum": [
                            "any",
                            "all"
                          ]
                        },
                        "excludeCampaignIds": {
                          "type": "array",
                          "maxItems": 50,
                          "items": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                        },
                        "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 session token",
        "x-access-scope": "marketing.view and assigned-product audience/segment access in the effective workspace.",
        "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-error-codes": [
          "MARKETING_CAMPAIGN_EXCLUSION_INVALID",
          "MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE",
          "MARKETING_CAMPAIGN_SELF_EXCLUSION"
        ],
        "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
                        }
                      },
                      "productMatch": {
                        "type": "string",
                        "enum": [
                          "any",
                          "all"
                        ]
                      },
                      "excludeCampaignIds": {
                        "type": "array",
                        "maxItems": 50,
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                      },
                      "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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": {
      "get": {
        "summary": "List permitted campaigns",
        "description": "The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "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": "HTTP 200: campaigns, total, page, pageSize.",
            "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
                                }
                              },
                              "productMatch": {
                                "type": "string",
                                "enum": [
                                  "any",
                                  "all"
                                ]
                              },
                              "excludeCampaignIds": {
                                "type": "array",
                                "maxItems": 50,
                                "items": {
                                  "type": "integer",
                                  "minimum": 1
                                },
                                "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                              },
                              "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"
                              },
                              "costCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "costBasis": {
                                "const": "current_policy_estimate"
                              },
                              "emailsSentCount": {
                                "type": "integer"
                              },
                              "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
                          },
                          "audienceEstimateStatus": {
                            "type": "string",
                            "enum": [
                              "ready",
                              "unavailable"
                            ]
                          }
                        },
                        "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 session token",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      },
      "post": {
        "summary": "Create a campaign draft",
        "description": "The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [],
        "responses": {
          "201": {
            "description": "HTTP 201: campaign, audience.",
            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                        },
                        "audienceEstimateStatus": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "unavailable"
                          ]
                        }
                      },
                      "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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 session token",
        "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-error-codes": [
          "MARKETING_CAMPAIGN_EXCLUSION_INVALID",
          "MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE",
          "MARKETING_CAMPAIGN_SELF_EXCLUSION"
        ],
        "x-source-files": [
          "routes/developerMarketingRoutes.js",
          "services/marketingCampaignService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "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
                        }
                      },
                      "productMatch": {
                        "type": "string",
                        "enum": [
                          "any",
                          "all"
                        ]
                      },
                      "excludeCampaignIds": {
                        "type": "array",
                        "maxItems": 50,
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                      },
                      "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/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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending. 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 session token",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      },
      "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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before 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": [
          {
            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                        },
                        "audienceEstimateStatus": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "unavailable"
                          ]
                        }
                      },
                      "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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 session token",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      },
      "patch": {
        "summary": "Update an editable campaign draft",
        "description": "The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. Only draft or scheduled content is editable; sent content is not rewritten. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: campaign, audience.",
            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                        },
                        "audienceEstimateStatus": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "unavailable"
                          ]
                        }
                      },
                      "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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 session token",
        "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": [
          "MARKETING_CAMPAIGN_EXCLUSION_INVALID",
          "MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE",
          "MARKETING_CAMPAIGN_SELF_EXCLUSION",
          "CAMPAIGN_NOT_EDITABLE"
        ],
        "x-source-files": [
          "routes/developerMarketingRoutes.js",
          "services/marketingCampaignService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "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
                        }
                      },
                      "productMatch": {
                        "type": "string",
                        "enum": [
                          "any",
                          "all"
                        ]
                      },
                      "excludeCampaignIds": {
                        "type": "array",
                        "maxItems": 50,
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                      },
                      "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/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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending. 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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                        },
                        "audienceEstimateStatus": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "unavailable"
                          ]
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/api/developer/marketing/campaigns/{campaignId}/cost-preview": {
      "get": {
        "summary": "Estimate the eligible audience against planned monthly spend",
        "description": "Requires marketing.view and assigned-product access to the campaign. Estimates the eligible current audience against the planned Eastern billing month, including existing accepted and reserved usage. No provider message or payment is sent, but monthly accounting counters can be initialized; this is not a zero-side-effect health probe. A preview is not a final invoice or a reservation. Billing, chosen budgets and suppression are checked again at dispatch. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "scheduledAt",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "required": false,
            "description": "Optional planned date within the next year."
          },
          {
            "name": "deliveryTimezone",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "required": false,
            "description": "IANA timezone for a planned local date; defaults to UTC."
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: enabled, monthlyLimitCents, monthStart, monthEnd, acceptedQuantity, reservedQuantity, usedCents, committedCents, remainingCents, includedQuantity, rateCentsPer1000, nearLimit, platformPlanningQuantity, platformCommittedQuantity, platformCapacityWarning, platformLimitEnforced, platformRemainingQuantity, canManageLimit, canReviewPlatformCapacity, recipientCount, additionalCents, projectedCents, withinLimit.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "monthlyLimitCents": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "minimum": 0,
                      "description": "Null means no developer spending limit, not free sending."
                    },
                    "monthStart": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "monthEnd": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "acceptedQuantity": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "reservedQuantity": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "usedCents": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "committedCents": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "remainingCents": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "minimum": 0
                    },
                    "includedQuantity": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "rateCentsPer1000": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "nearLimit": {
                      "type": "boolean"
                    },
                    "platformPlanningQuantity": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "platformCommittedQuantity": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "platformCapacityWarning": {
                      "type": "boolean"
                    },
                    "platformLimitEnforced": {
                      "type": "boolean"
                    },
                    "platformRemainingQuantity": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "canManageLimit": {
                      "type": "boolean"
                    },
                    "canReviewPlatformCapacity": {
                      "type": "boolean"
                    },
                    "recipientCount": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "additionalCents": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "projectedCents": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "withinLimit": {
                      "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 session token",
        "x-access-scope": "marketing.view and assigned-product campaign/audience access.",
        "x-request-fields": [
          "query scheduledAt: string. Optional planned date within the next year.",
          "query deliveryTimezone: string. IANA timezone for a planned local date; defaults to UTC."
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.",
        "security": [
          {
            "AccountSession": []
          }
        ],
        "x-contract-coverage": "Reviewed 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_COST_DATE_INVALID"
        ],
        "x-source-files": [
          "routes/developerMarketingRoutes.js",
          "services/marketingCampaignService.js",
          "services/marketingSpendControlService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/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. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending. 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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                        },
                        "audienceEstimateStatus": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "unavailable"
                          ]
                        }
                      },
                      "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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 session token",
        "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_CAMPAIGN_EXCLUSION_INVALID",
          "MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE",
          "MARKETING_CAMPAIGN_SELF_EXCLUSION"
        ],
        "x-source-files": [
          "routes/developerMarketingRoutes.js",
          "services/marketingCampaignService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                        },
                        "audienceEstimateStatus": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "unavailable"
                          ]
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/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 session token",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending. 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 session token",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before 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": [
          {
            "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 session token",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before 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": [
          {
            "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"
                    },
                    "costCents": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "costBasis": {
                      "const": "current_policy_estimate"
                    },
                    "emailsSentCount": {
                      "type": "integer"
                    },
                    "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 session token",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/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. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. A developer budget is optional and unlimited by default. Campaigns and automation share accepted and reserved usage in the planned Eastern month. Paid sends require a verified payment method; unpaid live bills and verification failures can pause marketing, including included sends. A platform planning warning alone is not a cap. Uncertain sends retain their reservation and must be reviewed rather than blindly resent. These holds do not revoke licenses or downloads. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending. 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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                        },
                        "audienceEstimateStatus": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "unavailable"
                          ]
                        }
                      },
                      "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"
                }
              }
            }
          },
          "402": {
            "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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_CAMPAIGN_EXCLUSION_INVALID",
          "MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE",
          "MARKETING_CAMPAIGN_SELF_EXCLUSION",
          "MARKETING_SPEND_LIMIT_REACHED",
          "MARKETING_PLATFORM_LIMIT_REACHED",
          "MARKETING_DELIVERY_UNCONFIRMED",
          "DEVELOPER_COST_PAYMENT_METHOD_REQUIRED",
          "DEVELOPER_COST_BILLING_RESTRICTED",
          "DEVELOPER_COST_BILLING_UNAVAILABLE",
          "DEVELOPER_COST_FUNDING_UNAVAILABLE",
          "CAMPAIGN_NOT_SENDING"
        ],
        "x-source-files": [
          "routes/developerMarketingRoutes.js",
          "services/marketingCampaignService.js",
          "services/marketingSpendControlService.js",
          "services/developerBillingGateService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "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 session token",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "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 session token",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/api/developer/marketing/campaigns/{campaignId}/schedule": {
      "post": {
        "summary": "Schedule an editable campaign",
        "description": "The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. Use a future date and valid IANA timezone. scheduled_at and timezone aliases are accepted. A developer budget is optional and unlimited by default. Campaigns and automation share accepted and reserved usage in the planned Eastern month. Paid sends require a verified payment method; unpaid live bills and verification failures can pause marketing, including included sends. A platform planning warning alone is not a cap. Uncertain sends retain their reservation and must be reviewed rather than blindly resent. These holds do not revoke licenses or downloads. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "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",
                      "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                        },
                        "audienceEstimateStatus": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "unavailable"
                          ]
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "402": {
            "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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_SPEND_LIMIT_REACHED",
          "MARKETING_PLATFORM_LIMIT_REACHED",
          "MARKETING_DELIVERY_UNCONFIRMED",
          "DEVELOPER_COST_PAYMENT_METHOD_REQUIRED",
          "DEVELOPER_COST_BILLING_RESTRICTED",
          "DEVELOPER_COST_BILLING_UNAVAILABLE",
          "DEVELOPER_COST_FUNDING_UNAVAILABLE",
          "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",
          "services/marketingSpendControlService.js",
          "services/developerBillingGateService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scheduledAt": {
                    "type": "string"
                  },
                  "deliveryTimezone": {
                    "type": "string"
                  }
                },
                "required": [
                  "scheduledAt"
                ],
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/developer/marketing/campaigns/{campaignId}/send-now": {
      "post": {
        "summary": "Queue and process the campaign audience",
        "description": "The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. The route can queue asynchronous work or report a processing batch. HTTP success is not inbox delivery; inspect recipients and reports. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. A developer budget is optional and unlimited by default. Campaigns and automation share accepted and reserved usage in the planned Eastern month. Paid sends require a verified payment method; unpaid live bills and verification failures can pause marketing, including included sends. A platform planning warning alone is not a cap. Uncertain sends retain their reservation and must be reviewed rather than blindly resent. These holds do not revoke licenses or downloads. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: campaign, queued, processed, sent, failed, deferred, skipped, remainingQueued, pausedUntil, async.",
            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                        },
                        "audienceEstimateStatus": {
                          "type": "string",
                          "enum": [
                            "ready",
                            "unavailable"
                          ]
                        }
                      },
                      "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"
                }
              }
            }
          },
          "402": {
            "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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_CAMPAIGN_EXCLUSION_INVALID",
          "MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE",
          "MARKETING_CAMPAIGN_SELF_EXCLUSION",
          "MARKETING_SPEND_LIMIT_REACHED",
          "MARKETING_PLATFORM_LIMIT_REACHED",
          "MARKETING_DELIVERY_UNCONFIRMED",
          "DEVELOPER_COST_PAYMENT_METHOD_REQUIRED",
          "DEVELOPER_COST_BILLING_RESTRICTED",
          "DEVELOPER_COST_BILLING_UNAVAILABLE",
          "DEVELOPER_COST_FUNDING_UNAVAILABLE",
          "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",
          "services/marketingSpendControlService.js",
          "services/developerBillingGateService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/api/developer/marketing/campaigns/{campaignId}/test": {
      "post": {
        "summary": "Send a campaign test to its permitted test recipient",
        "description": "The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: sent, provider, transactionId, recipientEmail, recipients.",
            "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 session token",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "to": {
                    "type": "string",
                    "format": "email"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before 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/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, costCents, costBasis, emailsSentCount, 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"
                    },
                    "costCents": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "costBasis": {
                      "const": "current_policy_estimate"
                    },
                    "emailsSentCount": {
                      "type": "integer"
                    },
                    "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 session token",
        "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"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/api/developer/marketing/contacts": {
      "get": {
        "summary": "List permitted marketing contacts",
        "description": "The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks.",
        "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": "HTTP 200: rows, total, page, pageSize, canExclude.",
            "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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/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 session token",
        "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 session token",
        "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 session token",
        "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": {
      "post": {
        "summary": "Import a confirmed contact list",
        "description": "The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. 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.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [],
        "responses": {
          "201": {
            "description": "HTTP 201: rowsUploaded, validRows, imported, updated, duplicates, skippedInvalidEmail, skippedMissingEmail, skippedUnsubscribed, skippedSuppressed, productAssociationsAdded, skipped, errors.",
            "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 session token",
        "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/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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/developerMarketingRoutes.js",
          "services/marketingCampaignService.js"
        ]
      }
    },
    "/api/developer/marketing/contacts/import/preview": {
      "post": {
        "summary": "Preview a contact import without sending",
        "description": "The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. 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.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: headers, suggestedMapping, previewRows, report.",
            "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 session token",
        "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/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.",
                            "properties": {
                              "includeFreeAcquisitions": {
                                "type": "boolean"
                              }
                            }
                          },
                          "type": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "audienceId": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "productId": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "includeFreeAcquisitions": {
                            "type": "boolean",
                            "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                          },
                          "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"
                              },
                              "type": {
                                "type": "string"
                              },
                              "purchaseRewardOfferId": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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. includeFreeAcquisitions must be a JSON boolean at top level or in metadata; a supplied top-level boolean takes precedence. Supported access flows include cross_sell_upsell, review_request, product_onboarding and product_update. Cross-sell and configured review/onboarding flows can respond to qualifying access events. Product-update audience eligibility does not make a grant a release trigger: a product-update event or deliberately reviewed history enrollment is still required. Saving the setting alone does not replay history or send messages. Explicit false retains paid-acquisition proof. A purchase-reward flow needs explicit true plus a program permitting free items; a conflicting program is rejected. Active recipient-owned access, popup verification, current state/expiry, enrollment eligibility and suppression checks remain required. Free access and reward coupons do not become paid orders. Retry of the same acquisition/program reuses its reward. 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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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",
          "includeFreeAcquisitions: boolean. For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program.",
          "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-error-codes": [
          "GROWTH_FLOW_ACQUISITION_SETTING_INVALID",
          "GROWTH_FLOW_REWARD_FREE_ACCESS_EXCLUDED"
        ],
        "x-source-files": [
          "routes/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js",
          "services/growthFlowAcquisitionPolicy.js",
          "services/growthFlowPurchaseRewardService.js"
        ],
        "x-source-revision": "ed7e5def3d871d9267d7cfd4ff1b76e9a162d4c8",
        "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.",
                    "properties": {
                      "includeFreeAcquisitions": {
                        "type": "boolean"
                      }
                    }
                  },
                  "type": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "audienceId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "productId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "includeFreeAcquisitions": {
                    "type": "boolean",
                    "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                  },
                  "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"
                      },
                      "type": {
                        "type": "string"
                      },
                      "purchaseRewardOfferId": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/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. includeFreeAcquisitions must be a JSON boolean at top level or in metadata; a supplied top-level boolean takes precedence. Supported access flows include cross_sell_upsell, review_request, product_onboarding and product_update. Cross-sell and configured review/onboarding flows can respond to qualifying access events. Product-update audience eligibility does not make a grant a release trigger: a product-update event or deliberately reviewed history enrollment is still required. Saving the setting alone does not replay history or send messages. Explicit false retains paid-acquisition proof. A purchase-reward flow needs explicit true plus a program permitting free items; a conflicting program is rejected. Active recipient-owned access, popup verification, current state/expiry, enrollment eligibility and suppression checks remain required. Free access and reward coupons do not become paid orders. Retry of the same acquisition/program reuses its reward. 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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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",
          "includeFreeAcquisitions: boolean. For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program.",
          "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-error-codes": [
          "GROWTH_FLOW_ACQUISITION_SETTING_INVALID",
          "GROWTH_FLOW_REWARD_FREE_ACCESS_EXCLUDED"
        ],
        "x-source-files": [
          "routes/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js",
          "services/growthFlowAcquisitionPolicy.js",
          "services/growthFlowPurchaseRewardService.js"
        ],
        "x-source-revision": "ed7e5def3d871d9267d7cfd4ff1b76e9a162d4c8",
        "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.",
                    "properties": {
                      "includeFreeAcquisitions": {
                        "type": "boolean"
                      }
                    }
                  },
                  "type": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "audienceId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "productId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "includeFreeAcquisitions": {
                    "type": "boolean",
                    "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                  },
                  "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"
                      },
                      "type": {
                        "type": "string"
                      },
                      "purchaseRewardOfferId": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js"
        ]
      }
    },
    "/api/developer/marketing/growth-flows/{flowId}/enroll-previous": {
      "post": {
        "summary": "Schedule historical eligible customers for an active growth flow",
        "description": "Requires an active flow and enabled automation. A new job returns started:true, jobId and eligibleRecipients. The same pending configuration returns started:false, alreadyRunning:true and the existing jobId, without a fresh eligible count. Changed pending configuration can supersede earlier fanout. No eligible recipients returns started:false, eligibleRecipients:0 and no jobId. Messages wait at least 24 hours; recipient eligibility is checked again before sending. This is a queue mutation, not an immediate-send or harmless preview.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [
          {
            "name": "flowId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: review the response schema below.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "started": {
                          "const": true
                        },
                        "jobId": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 1
                            },
                            {
                              "type": "string",
                              "pattern": "^[1-9][0-9]*$"
                            }
                          ]
                        },
                        "eligibleRecipients": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "minimumWaitHours": {
                          "const": 24
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "started",
                        "jobId",
                        "eligibleRecipients",
                        "minimumWaitHours"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "started": {
                          "const": false
                        },
                        "alreadyRunning": {
                          "const": true
                        },
                        "jobId": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 1
                            },
                            {
                              "type": "string",
                              "pattern": "^[1-9][0-9]*$"
                            }
                          ]
                        },
                        "minimumWaitHours": {
                          "const": 24
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "started",
                        "alreadyRunning",
                        "jobId",
                        "minimumWaitHours"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "started": {
                          "const": false
                        },
                        "eligibleRecipients": {
                          "const": 0
                        },
                        "minimumWaitHours": {
                          "const": 24
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "started",
                        "eligibleRecipients",
                        "minimumWaitHours"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "marketing.manage and all-products workspace scope. Current audience eligibility and suppression are rechecked.",
        "x-request-fields": [
          "scope: \"all_previous\" (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/growthFlowEligibilityService.js",
          "services/emailGrowthFlowService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scope": {
                    "const": "all_previous"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "scope"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/marketing/growth-flows/{flowId}/history-preview": {
      "get": {
        "summary": "Preview all previous eligible recipients without enrolling them",
        "description": "A count is a current eligibility estimate, not a delivery promise. It shares the enrollment query and reflects current product access, audience, flow configuration, prior work and marketing restrictions. flowId may be a decimal string. canEnroll is not proof that the master automation setting is enabled.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [
          {
            "name": "flowId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: flowId, name, type, status, eligibleRecipients, reason, minimumWaitHours, scope, canEnroll.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "flowId": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "minimum": 1
                        },
                        {
                          "type": "string",
                          "pattern": "^[1-9][0-9]*$"
                        }
                      ],
                      "description": "Database workflow identifier; accept its decimal string form without treating it as a UUID."
                    },
                    "name": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "eligibleRecipients": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "reason": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "minimumWaitHours": {
                      "const": 24
                    },
                    "scope": {
                      "const": "all_previous"
                    },
                    "canEnroll": {
                      "type": "boolean",
                      "description": "Hint from active workflow, configuration and eligible count. Enrollment separately requires automation to be enabled and rechecks eligibility."
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "marketing.manage and all-products workspace scope. Current audience eligibility and suppression are rechecked.",
        "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/growthFlowEligibilityService.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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/developerMarketingRoutes.js",
          "services/marketingAutomationService.js",
          "services/emailGrowthFlowService.js"
        ]
      }
    },
    "/api/developer/marketing/growth-flows/{flowId}/recipients": {
      "get": {
        "summary": "Review flow recipients",
        "description": "For status=queued, inspect sendHoldCode, failureReason and nextRetryAt separately from scheduledFor. A funding hold keeps the planned date and uses a separate retry deadline, normally set 15 minutes after the deferred attempt. Worker selection and claim both respect that deadline. Once funding and spend checks succeed, held work can retry automatically; provider availability, active flow, consent, ownership and queue eligibility still apply. Do not reset the flow or use Retry unconfirmed for an ordinary funding pause. The row may remain queued while sending is paused; a past scheduledFor is not proof of a send. 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",
                            "description": "Planned send date. For a queued funding hold, preserves not_before when recorded, otherwise scheduled_for; not the next funding-retry time."
                          },
                          "sendHoldCode": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Queued spend/funding hold code, otherwise null. A hold is not provider acceptance or delivery_unknown."
                          },
                          "nextRetryAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time",
                            "description": "Queued funding retry eligibility from spendHoldRetryAt, with a legacy scheduled_for fallback. Otherwise null. Not a guaranteed send 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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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/email-preview": {
      "post": {
        "summary": "Render a branded primary or reward email without sending",
        "description": "Uses the maintained delivery renderer and current branding. headerEnabled:false removes the header; headerLogo accepts a supported HTTP(S) URL or an empty value. Cross-sell trigger products and recommendations are separate. Preview is not an email send, inbox-rendering guarantee, consent change or recipient enrollment.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: subject, html, text.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "subject": {
                      "type": "string"
                    },
                    "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"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "marketing.manage and all-products workspace scope. Current audience eligibility and suppression are rechecked.",
        "x-request-fields": [
          "type: string",
          "productId: integer",
          "reward: boolean",
          "email: object",
          "metadata: 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/growthFlowEligibilityService.js",
          "services/emailGrowthFlowService.js"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string"
                  },
                  "productId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "reward": {
                    "type": "boolean"
                  },
                  "email": {
                    "type": "object",
                    "properties": {
                      "subject": {
                        "type": "string"
                      },
                      "body": {
                        "type": "string"
                      },
                      "bodyHtml": {
                        "type": "string"
                      },
                      "emailDesign": {
                        "type": "object",
                        "properties": {
                          "headerEnabled": {
                            "type": "boolean"
                          },
                          "headerLogo": {
                            "type": "string"
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "additionalProperties": true
                  },
                  "metadata": {
                    "type": "object",
                    "properties": {
                      "triggerProductIds": {
                        "type": "array",
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        }
                      },
                      "recommendedProductIds": {
                        "type": "array",
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        }
                      }
                    },
                    "additionalProperties": true
                  }
                },
                "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. Returns static promo codes separately from purchase-reward programs. A selected inactive reward may be included for editing; it is not eligible for new reward issuance. 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": ""
          },
          {
            "name": "selectedRewardId",
            "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
                      }
                    },
                    "purchaseRewards": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "title": {
                            "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "x-request-fields": [
          "query search: string",
          "query selectedId: integer",
          "query selectedRewardId: 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",
          "services/growthFlowPurchaseRewardService.js"
        ]
      }
    },
    "/api/developer/marketing/growth-flows/purchase-rewards": {
      "post": {
        "summary": "Create an order-scoped reward program for owned trigger products",
        "description": "Creates an active post_purchase_coupon program for the owned trigger products, not a shared coupon code. Percent is the default discount type and cannot exceed 100; amount is a dollar discount. The helper sets requiredQuantity:1 and order-scoped paid grants. A qualifying paid order can issue a recipient-specific coupon. A cross-sell flow explicitly enabling includeFreeAcquisitions can instead use verified active access if the program allows free items and its quantity rules are satisfied; that grant retains entitlement provenance, not a fabricated order. This request alone does not send email, enroll an audience or issue a coupon. Existing promotion validation and marketing.manage/all-products checks apply.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/growth-flows"
        },
        "parameters": [],
        "responses": {
          "201": {
            "description": "HTTP 201: offer.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "offer": {
                      "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "x-request-fields": [
          "title: string (required)",
          "productIds: array (required)",
          "discountType: percent | amount",
          "discountValue: number (required)",
          "codePrefix: 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",
          "services/growthFlowPurchaseRewardService.js",
          "services/developerPromotionService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "minLength": 1,
                    "pattern": "\\S"
                  },
                  "productIds": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "minItems": 1
                  },
                  "discountType": {
                    "type": "string",
                    "enum": [
                      "percent",
                      "amount"
                    ]
                  },
                  "discountValue": {
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  "codePrefix": {
                    "type": "string"
                  }
                },
                "required": [
                  "title",
                  "productIds",
                  "discountValue"
                ],
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/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.",
                            "properties": {
                              "includeFreeAcquisitions": {
                                "type": "boolean"
                              }
                            }
                          },
                          "type": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "audienceId": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "productId": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "includeFreeAcquisitions": {
                            "type": "boolean",
                            "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                          },
                          "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"
                              },
                              "type": {
                                "type": "string"
                              },
                              "purchaseRewardOfferId": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/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.",
                          "properties": {
                            "includeFreeAcquisitions": {
                              "type": "boolean"
                            }
                          }
                        },
                        "type": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "audienceId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "includeFreeAcquisitions": {
                          "type": "boolean",
                          "description": "For supported product-access flows, explicit true admits verified active free access; false requires qualifying paid acquisition. Omission preserves the existing flow/default behavior. A supplied top-level boolean takes precedence over metadata.includeFreeAcquisitions. Product-update audience eligibility does not make an access grant a release trigger. Purchase-reward flows remain paid-only unless explicitly enabled and allowed by the reward program."
                        },
                        "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"
                            },
                            "type": {
                              "type": "string"
                            },
                            "purchaseRewardOfferId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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 session token",
        "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
                        }
                      },
                      "productMatch": {
                        "type": "string",
                        "enum": [
                          "any",
                          "all"
                        ]
                      },
                      "excludeCampaignIds": {
                        "type": "array",
                        "maxItems": 50,
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                      },
                      "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
                                }
                              },
                              "productMatch": {
                                "type": "string",
                                "enum": [
                                  "any",
                                  "all"
                                ]
                              },
                              "excludeCampaignIds": {
                                "type": "array",
                                "maxItems": 50,
                                "items": {
                                  "type": "integer",
                                  "minimum": 1
                                },
                                "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                              },
                              "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
                                    }
                                  },
                                  "productMatch": {
                                    "type": "string",
                                    "enum": [
                                      "any",
                                      "all"
                                    ]
                                  },
                                  "excludeCampaignIds": {
                                    "type": "array",
                                    "maxItems": 50,
                                    "items": {
                                      "type": "integer",
                                      "minimum": 1
                                    },
                                    "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                                  },
                                  "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
                                    }
                                  },
                                  "productMatch": {
                                    "type": "string",
                                    "enum": [
                                      "any",
                                      "all"
                                    ]
                                  },
                                  "excludeCampaignIds": {
                                    "type": "array",
                                    "maxItems": 50,
                                    "items": {
                                      "type": "integer",
                                      "minimum": 1
                                    },
                                    "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                                  },
                                  "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 session token",
        "x-access-scope": "marketing.view and assigned-product audience/segment access in the effective workspace.",
        "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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
                                  }
                                },
                                "productMatch": {
                                  "type": "string",
                                  "enum": [
                                    "any",
                                    "all"
                                  ]
                                },
                                "excludeCampaignIds": {
                                  "type": "array",
                                  "maxItems": 50,
                                  "items": {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                                },
                                "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
                                  }
                                },
                                "productMatch": {
                                  "type": "string",
                                  "enum": [
                                    "any",
                                    "all"
                                  ]
                                },
                                "excludeCampaignIds": {
                                  "type": "array",
                                  "maxItems": 50,
                                  "items": {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                                },
                                "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 session token",
        "x-access-scope": "marketing.view + marketing.manage and assigned-product audience/segment access in the effective workspace.",
        "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
                        }
                      },
                      "productMatch": {
                        "type": "string",
                        "enum": [
                          "any",
                          "all"
                        ]
                      },
                      "excludeCampaignIds": {
                        "type": "array",
                        "maxItems": 50,
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                      },
                      "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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
                                  }
                                },
                                "productMatch": {
                                  "type": "string",
                                  "enum": [
                                    "any",
                                    "all"
                                  ]
                                },
                                "excludeCampaignIds": {
                                  "type": "array",
                                  "maxItems": 50,
                                  "items": {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                                },
                                "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
                                  }
                                },
                                "productMatch": {
                                  "type": "string",
                                  "enum": [
                                    "any",
                                    "all"
                                  ]
                                },
                                "excludeCampaignIds": {
                                  "type": "array",
                                  "maxItems": 50,
                                  "items": {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                                },
                                "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 session token",
        "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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
                                  }
                                },
                                "productMatch": {
                                  "type": "string",
                                  "enum": [
                                    "any",
                                    "all"
                                  ]
                                },
                                "excludeCampaignIds": {
                                  "type": "array",
                                  "maxItems": 50,
                                  "items": {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                                },
                                "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
                                  }
                                },
                                "productMatch": {
                                  "type": "string",
                                  "enum": [
                                    "any",
                                    "all"
                                  ]
                                },
                                "excludeCampaignIds": {
                                  "type": "array",
                                  "maxItems": 50,
                                  "items": {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                                },
                                "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 session token",
        "x-access-scope": "marketing.view + marketing.manage and assigned-product audience/segment access in the effective workspace.",
        "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
                        }
                      },
                      "productMatch": {
                        "type": "string",
                        "enum": [
                          "any",
                          "all"
                        ]
                      },
                      "excludeCampaignIds": {
                        "type": "array",
                        "maxItems": 50,
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                      },
                      "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/settings": {
      "get": {
        "summary": "Read sender and marketing settings",
        "description": "The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: 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."
                        },
                        "spending": {
                          "type": "object",
                          "properties": {
                            "enabled": {
                              "type": "boolean"
                            },
                            "monthlyLimitCents": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "minimum": 0,
                              "description": "Null means no developer spending limit, not free sending."
                            },
                            "monthStart": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "monthEnd": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "acceptedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "reservedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "usedCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "committedCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "remainingCents": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "minimum": 0
                            },
                            "includedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "rateCentsPer1000": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "nearLimit": {
                              "type": "boolean"
                            },
                            "platformPlanningQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "platformCommittedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "platformCapacityWarning": {
                              "type": "boolean"
                            },
                            "platformLimitEnforced": {
                              "type": "boolean"
                            },
                            "platformRemainingQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "canManageLimit": {
                              "type": "boolean"
                            },
                            "canReviewPlatformCapacity": {
                              "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"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/developerMarketingRoutes.js",
          "services/marketingCampaignService.js"
        ]
      },
      "patch": {
        "summary": "Update workspace-wide sender settings",
        "description": "The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. From address must be verified. Requires marketing.manage and all-products scope. Only the account owner or authorized platform owner can set or clear monthlySpendLimitUsd; other authorized teammates may retain their ordinary sender-setting edits without that field. Budgets are optional, unlimited by default, shared by campaigns and Growth Flows, and not a credit against the Full Store minimum. This setting does not bypass billing readiness, 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.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: 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."
                        },
                        "spending": {
                          "type": "object",
                          "properties": {
                            "enabled": {
                              "type": "boolean"
                            },
                            "monthlyLimitCents": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "minimum": 0,
                              "description": "Null means no developer spending limit, not free sending."
                            },
                            "monthStart": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "monthEnd": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "acceptedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "reservedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "usedCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "committedCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "remainingCents": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "minimum": 0
                            },
                            "includedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "rateCentsPer1000": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "nearLimit": {
                              "type": "boolean"
                            },
                            "platformPlanningQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "platformCommittedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "platformCapacityWarning": {
                              "type": "boolean"
                            },
                            "platformLimitEnforced": {
                              "type": "boolean"
                            },
                            "platformRemainingQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "canManageLimit": {
                              "type": "boolean"
                            },
                            "canReviewPlatformCapacity": {
                              "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"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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",
          "monthlySpendLimitUsd: string,number,null. USD with up to two decimal places. Omit to preserve, clear with an empty string or null for unlimited, or use 0 for included sends only. Changing this field requires account-owner authority."
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host 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_SPEND_OWNER_REQUIRED",
          "MARKETING_SPEND_LIMIT_INVALID"
        ],
        "x-source-files": [
          "routes/developerMarketingRoutes.js",
          "services/marketingCampaignService.js",
          "services/marketingSpendControlService.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"
                  },
                  "monthlySpendLimitUsd": {
                    "type": [
                      "string",
                      "number",
                      "null"
                    ],
                    "description": "USD with up to two decimal places. Omit to preserve, clear with an empty string or null for unlimited, or use 0 for included sends only. Changing this field requires account-owner authority."
                  }
                },
                "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."
                        },
                        "spending": {
                          "type": "object",
                          "properties": {
                            "enabled": {
                              "type": "boolean"
                            },
                            "monthlyLimitCents": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "minimum": 0,
                              "description": "Null means no developer spending limit, not free sending."
                            },
                            "monthStart": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "monthEnd": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "acceptedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "reservedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "usedCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "committedCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "remainingCents": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "minimum": 0
                            },
                            "includedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "rateCentsPer1000": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "nearLimit": {
                              "type": "boolean"
                            },
                            "platformPlanningQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "platformCommittedQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "platformCapacityWarning": {
                              "type": "boolean"
                            },
                            "platformLimitEnforced": {
                              "type": "boolean"
                            },
                            "platformRemainingQuantity": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "canManageLimit": {
                              "type": "boolean"
                            },
                            "canReviewPlatformCapacity": {
                              "type": "boolean"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/developerMarketingRoutes.js",
          "services/marketingCampaignService.js"
        ]
      }
    },
    "/api/developer/marketing/suppressions": {
      "get": {
        "summary": "List saved marketing suppressions",
        "description": "The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks.",
        "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": "HTTP 200: suppressions.",
            "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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still apply.",
        "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/marketing/usage": {
      "get": {
        "summary": "Read monthly marketing usage",
        "description": "The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. Current live usage estimates use one shared allowance per Eastern calendar month, including campaigns and automation. total_cents is a current-policy estimate, not a finalized invoice, historical payment or waiver. Campaign reports allocate overage blocks in actual send order instead of giving each campaign a separate allowance.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/email-marketing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: usage, includedMonthlyEmails, costBasis.",
            "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"
                    },
                    "costBasis": {
                      "const": "current_policy_estimate"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/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 session token",
        "x-access-scope": "marketing.view in the effective developer workspace; operation-specific audience checks still 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/developerMarketingRoutes.js",
          "services/marketingCampaignService.js",
          "services/marketingBillingUsageReportingService.js"
        ]
      }
    },
    "/api/developer/meta-capi": {
      "delete": {
        "summary": "Disconnect forwarding and remove saved destination credentials",
        "description": "Cancels pending events and removes saved checkout measurement snapshots. Provider-side history is separate. No browser Pixel is installed by this operation.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/meta-capi"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: destinationId, hasToken, mode, eventNames, testEventCode, verifiedAt, configured, encryptionReady, ready, workerEnabled, lastError, apiVersion, canManage, counts, lastSuccess, events.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "destinationId": {
                      "type": "string"
                    },
                    "hasToken": {
                      "type": "boolean"
                    },
                    "mode": {
                      "type": "string",
                      "enum": [
                        "disabled",
                        "testing",
                        "live"
                      ]
                    },
                    "eventNames": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "testEventCode": {
                      "type": "string"
                    },
                    "verifiedAt": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "date-time"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "configured": {
                      "type": "boolean"
                    },
                    "encryptionReady": {
                      "type": "boolean"
                    },
                    "ready": {
                      "type": "boolean"
                    },
                    "workerEnabled": {
                      "type": "boolean"
                    },
                    "lastError": {
                      "type": "string"
                    },
                    "apiVersion": {
                      "type": "string"
                    },
                    "canManage": {
                      "type": "boolean"
                    },
                    "counts": {
                      "type": "object",
                      "properties": {},
                      "additionalProperties": true
                    },
                    "lastSuccess": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "date-time"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "event_name": {
                            "type": "string"
                          },
                          "event_id": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "attempts": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "replay_count": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "explanation": {
                            "type": "string"
                          },
                          "canReplay": {
                            "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 session token",
        "x-access-scope": "settings.view and all-products scope for settings reads; settings.manage additionally required for saves, connection tests, replay and disconnect.",
        "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/developerMetaCapiRoutes.js",
          "routes/metaCapiRoutes.js",
          "services/developerMetaCapiService.js",
          "services/metaCapiDeliveryService.js",
          "services/metaCapiPayload.js"
        ]
      },
      "get": {
        "summary": "Read destination readiness and redacted delivery outcomes",
        "description": "",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/meta-capi"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: destinationId, hasToken, mode, eventNames, testEventCode, verifiedAt, configured, encryptionReady, ready, workerEnabled, lastError, apiVersion, canManage, counts, lastSuccess, events.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "destinationId": {
                      "type": "string"
                    },
                    "hasToken": {
                      "type": "boolean"
                    },
                    "mode": {
                      "type": "string",
                      "enum": [
                        "disabled",
                        "testing",
                        "live"
                      ]
                    },
                    "eventNames": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "testEventCode": {
                      "type": "string"
                    },
                    "verifiedAt": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "date-time"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "configured": {
                      "type": "boolean"
                    },
                    "encryptionReady": {
                      "type": "boolean"
                    },
                    "ready": {
                      "type": "boolean"
                    },
                    "workerEnabled": {
                      "type": "boolean"
                    },
                    "lastError": {
                      "type": "string"
                    },
                    "apiVersion": {
                      "type": "string"
                    },
                    "canManage": {
                      "type": "boolean"
                    },
                    "counts": {
                      "type": "object",
                      "properties": {},
                      "additionalProperties": true
                    },
                    "lastSuccess": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "date-time"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "event_name": {
                            "type": "string"
                          },
                          "event_id": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "attempts": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "replay_count": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "explanation": {
                            "type": "string"
                          },
                          "canReplay": {
                            "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 session token",
        "x-access-scope": "settings.view and all-products scope for settings reads; settings.manage additionally required for saves, connection tests, replay and disconnect.",
        "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/developerMetaCapiRoutes.js",
          "routes/metaCapiRoutes.js",
          "services/developerMetaCapiService.js",
          "services/metaCapiDeliveryService.js",
          "services/metaCapiPayload.js"
        ]
      },
      "put": {
        "summary": "Save an encrypted Meta destination and permitted event set",
        "description": "An access token is required on initial setup. Save new/replaced credentials disabled, save an Events Manager test code, run the synthetic test, then inspect accepted/verified state before activation. testing requires testEventCode. Changing configuration cancels queued work for the old generation; history is not rerouted.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/meta-capi"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: destinationId, hasToken, mode, eventNames, testEventCode, verifiedAt, configured, encryptionReady, ready, workerEnabled, lastError, apiVersion, canManage, counts, lastSuccess, events.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "destinationId": {
                      "type": "string"
                    },
                    "hasToken": {
                      "type": "boolean"
                    },
                    "mode": {
                      "type": "string",
                      "enum": [
                        "disabled",
                        "testing",
                        "live"
                      ]
                    },
                    "eventNames": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "testEventCode": {
                      "type": "string"
                    },
                    "verifiedAt": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "date-time"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "configured": {
                      "type": "boolean"
                    },
                    "encryptionReady": {
                      "type": "boolean"
                    },
                    "ready": {
                      "type": "boolean"
                    },
                    "workerEnabled": {
                      "type": "boolean"
                    },
                    "lastError": {
                      "type": "string"
                    },
                    "apiVersion": {
                      "type": "string"
                    },
                    "canManage": {
                      "type": "boolean"
                    },
                    "counts": {
                      "type": "object",
                      "properties": {},
                      "additionalProperties": true
                    },
                    "lastSuccess": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "date-time"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "event_name": {
                            "type": "string"
                          },
                          "event_id": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "attempts": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "replay_count": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "explanation": {
                            "type": "string"
                          },
                          "canReplay": {
                            "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 session token",
        "x-access-scope": "settings.view and all-products scope for settings reads; settings.manage additionally required for saves, connection tests, replay and disconnect.",
        "x-request-fields": [
          "destinationId: string (required)",
          "accessToken: string",
          "mode: disabled | testing | live",
          "testEventCode: string",
          "eventNames: 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/developerMetaCapiRoutes.js",
          "routes/metaCapiRoutes.js",
          "services/developerMetaCapiService.js",
          "services/metaCapiDeliveryService.js",
          "services/metaCapiPayload.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "destinationId": {
                    "type": "string",
                    "pattern": "^[0-9]{5,30}$"
                  },
                  "accessToken": {
                    "type": "string",
                    "writeOnly": true
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "disabled",
                      "testing",
                      "live"
                    ]
                  },
                  "testEventCode": {
                    "type": "string"
                  },
                  "eventNames": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "PageView",
                        "ViewContent",
                        "AddToCart",
                        "InitiateCheckout",
                        "Purchase"
                      ]
                    }
                  }
                },
                "additionalProperties": true,
                "required": [
                  "destinationId",
                  "eventNames"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/meta-capi/events/{eventId}/replay": {
      "post": {
        "summary": "Requeue a recent eligible failed event for the same destination",
        "description": "Only failed events with retained payload, fewer than three replays, current destination/generation, recent original time and no suppression are eligible. Replay preserves event identity/time and cannot bypass expiry or recipient restrictions.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/meta-capi"
        },
        "parameters": [
          {
            "name": "eventId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: destinationId, hasToken, mode, eventNames, testEventCode, verifiedAt, configured, encryptionReady, ready, workerEnabled, lastError, apiVersion, canManage, counts, lastSuccess, events.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "destinationId": {
                      "type": "string"
                    },
                    "hasToken": {
                      "type": "boolean"
                    },
                    "mode": {
                      "type": "string",
                      "enum": [
                        "disabled",
                        "testing",
                        "live"
                      ]
                    },
                    "eventNames": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "testEventCode": {
                      "type": "string"
                    },
                    "verifiedAt": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "date-time"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "configured": {
                      "type": "boolean"
                    },
                    "encryptionReady": {
                      "type": "boolean"
                    },
                    "ready": {
                      "type": "boolean"
                    },
                    "workerEnabled": {
                      "type": "boolean"
                    },
                    "lastError": {
                      "type": "string"
                    },
                    "apiVersion": {
                      "type": "string"
                    },
                    "canManage": {
                      "type": "boolean"
                    },
                    "counts": {
                      "type": "object",
                      "properties": {},
                      "additionalProperties": true
                    },
                    "lastSuccess": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "date-time"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "event_name": {
                            "type": "string"
                          },
                          "event_id": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "attempts": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "replay_count": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "explanation": {
                            "type": "string"
                          },
                          "canReplay": {
                            "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 session token",
        "x-access-scope": "settings.view and all-products scope for settings reads; settings.manage additionally required for saves, connection tests, replay and disconnect.",
        "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/developerMetaCapiRoutes.js",
          "routes/metaCapiRoutes.js",
          "services/developerMetaCapiService.js",
          "services/metaCapiDeliveryService.js",
          "services/metaCapiPayload.js"
        ]
      }
    },
    "/api/developer/meta-capi/test": {
      "post": {
        "summary": "Queue one explicitly synthetic connection test",
        "description": "Requires a saved destination/token and Events Manager test code. This queues an external test event; do not use as a harmless health read. HTTP success does not establish provider acceptance, Events Manager visibility or ad attribution. Inspect the returned event status after worker processing.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/meta-capi"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: destinationId, hasToken, mode, eventNames, testEventCode, verifiedAt, configured, encryptionReady, ready, workerEnabled, lastError, apiVersion, canManage, counts, lastSuccess, events.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "destinationId": {
                      "type": "string"
                    },
                    "hasToken": {
                      "type": "boolean"
                    },
                    "mode": {
                      "type": "string",
                      "enum": [
                        "disabled",
                        "testing",
                        "live"
                      ]
                    },
                    "eventNames": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "testEventCode": {
                      "type": "string"
                    },
                    "verifiedAt": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "date-time"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "configured": {
                      "type": "boolean"
                    },
                    "encryptionReady": {
                      "type": "boolean"
                    },
                    "ready": {
                      "type": "boolean"
                    },
                    "workerEnabled": {
                      "type": "boolean"
                    },
                    "lastError": {
                      "type": "string"
                    },
                    "apiVersion": {
                      "type": "string"
                    },
                    "canManage": {
                      "type": "boolean"
                    },
                    "counts": {
                      "type": "object",
                      "properties": {},
                      "additionalProperties": true
                    },
                    "lastSuccess": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "date-time"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "event_name": {
                            "type": "string"
                          },
                          "event_id": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "attempts": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "replay_count": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "explanation": {
                            "type": "string"
                          },
                          "canReplay": {
                            "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 session token",
        "x-access-scope": "settings.view and all-products scope for settings reads; settings.manage additionally required for saves, connection tests, replay and disconnect.",
        "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/developerMetaCapiRoutes.js",
          "routes/metaCapiRoutes.js",
          "services/developerMetaCapiService.js",
          "services/metaCapiDeliveryService.js",
          "services/metaCapiPayload.js"
        ]
      }
    },
    "/api/developer/notices/campaigns": {
      "get": {
        "summary": "List scoped notice drafts and publication states",
        "description": "Returns at most 200 rows. scheduled/expired are date-filtered views of published records. Current Brand Manager values are overlaid on returned draft branding.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [
          {
            "name": "productId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "published",
                "paused",
                "archived",
                "scheduled",
                "expired"
              ]
            }
          },
          {
            "name": "noticeType",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: review the response schema below.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "product_id": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "product_ids": {
                        "type": "array",
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        }
                      },
                      "scope_mode": {
                        "type": "string"
                      },
                      "version": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "state": {
                        "type": "string",
                        "enum": [
                          "draft",
                          "published",
                          "paused",
                          "archived"
                        ]
                      },
                      "draft": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "body": {
                            "type": "string"
                          },
                          "brand": {
                            "type": "string"
                          },
                          "color": {
                            "type": "string"
                          },
                          "audience": {
                            "type": "string",
                            "enum": [
                              "public",
                              "customers"
                            ]
                          },
                          "noticeType": {
                            "type": "string",
                            "enum": [
                              "announcement",
                              "content",
                              "plugin_update",
                              "download",
                              "promotion"
                            ]
                          },
                          "trigger": {
                            "type": "string",
                            "enum": [
                              "editor_opened",
                              "editor_available",
                              "control_clicked"
                            ]
                          },
                          "controlId": {
                            "type": "string"
                          },
                          "timezone": {
                            "type": "string"
                          },
                          "startAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "endAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "delaySeconds": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 86400
                          },
                          "priority": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 100
                          },
                          "maxDisplays": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                          },
                          "cooldownSeconds": {
                            "type": "integer",
                            "minimum": 60,
                            "maximum": 2592000
                          },
                          "actions": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "type": {
                                  "type": "string",
                                  "enum": [
                                    "https",
                                    "navigate",
                                    "dismiss",
                                    "resource",
                                    "download",
                                    "instructions"
                                  ]
                                },
                                "label": {
                                  "type": "string"
                                },
                                "target": {
                                  "type": "string"
                                },
                                "presentation": {
                                  "type": "string",
                                  "enum": [
                                    "button",
                                    "link"
                                  ]
                                },
                                "resource": {
                                  "type": "object",
                                  "properties": {
                                    "id": {
                                      "type": "string"
                                    },
                                    "kind": {
                                      "type": "string"
                                    },
                                    "productId": {
                                      "type": "integer",
                                      "minimum": 1
                                    },
                                    "url": {
                                      "type": "string"
                                    },
                                    "downloadAvailable": {
                                      "type": "boolean"
                                    }
                                  },
                                  "additionalProperties": true
                                }
                              },
                              "additionalProperties": true
                            },
                            "maxItems": 4
                          },
                          "action": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "type": {
                                "type": "string",
                                "enum": [
                                  "https",
                                  "navigate",
                                  "dismiss",
                                  "resource",
                                  "download",
                                  "instructions"
                                ]
                              },
                              "label": {
                                "type": "string"
                              },
                              "target": {
                                "type": "string"
                              },
                              "presentation": {
                                "type": "string",
                                "enum": [
                                  "button",
                                  "link"
                                ]
                              },
                              "resource": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "kind": {
                                    "type": "string"
                                  },
                                  "productId": {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  "url": {
                                    "type": "string"
                                  },
                                  "downloadAvailable": {
                                    "type": "boolean"
                                  }
                                },
                                "additionalProperties": true
                              }
                            },
                            "additionalProperties": true,
                            "description": "Legacy single-action input; prefer actions for new integrations."
                          },
                          "resourceId": {
                            "anyOf": [
                              {
                                "type": "string",
                                "format": "uuid"
                              },
                              {
                                "const": ""
                              }
                            ]
                          },
                          "linkedProductId": {
                            "anyOf": [
                              {
                                "type": "integer",
                                "minimum": 1
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "productUrl": {
                            "type": "string"
                          }
                        },
                        "additionalProperties": true,
                        "required": [
                          "name",
                          "title",
                          "body",
                          "audience",
                          "trigger",
                          "timezone",
                          "startAt",
                          "endAt",
                          "delaySeconds",
                          "priority",
                          "maxDisplays",
                          "cooldownSeconds"
                        ],
                        "anyOf": [
                          {
                            "required": [
                              "actions"
                            ]
                          },
                          {
                            "required": [
                              "action"
                            ]
                          }
                        ]
                      },
                      "updated_at": {
                        "type": "string",
                        "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 session token",
        "x-access-scope": "marketing.view to read; marketing.manage to write. Effective developer and every assigned product in a notice/reference must be permitted.",
        "x-request-fields": [
          "query productId: integer",
          "query state: string",
          "query noticeType: string",
          "query search: string",
          "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-source-files": [
          "routes/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ]
      },
      "post": {
        "summary": "Save a versioned draft without publishing or sending email",
        "description": "Selected scope needs productIds. all_integrated snapshots the currently enabled permitted products, not future products. Updating an existing ID requires expectedVersion; saving creates a new immutable version, returns the notice to draft and cancels outstanding deliveries. Brand/color come from Brand Manager and cannot be overridden per notice. Non-announcements need the corresponding product/resource and resource/download actions.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: id, product_id, product_ids, scope_mode, version, state, draft, updated_at.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "product_id": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "product_ids": {
                      "type": "array",
                      "items": {
                        "type": "integer",
                        "minimum": 1
                      }
                    },
                    "scope_mode": {
                      "type": "string"
                    },
                    "version": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "state": {
                      "type": "string",
                      "enum": [
                        "draft",
                        "published",
                        "paused",
                        "archived"
                      ]
                    },
                    "draft": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "title": {
                          "type": "string"
                        },
                        "body": {
                          "type": "string"
                        },
                        "brand": {
                          "type": "string"
                        },
                        "color": {
                          "type": "string"
                        },
                        "audience": {
                          "type": "string",
                          "enum": [
                            "public",
                            "customers"
                          ]
                        },
                        "noticeType": {
                          "type": "string",
                          "enum": [
                            "announcement",
                            "content",
                            "plugin_update",
                            "download",
                            "promotion"
                          ]
                        },
                        "trigger": {
                          "type": "string",
                          "enum": [
                            "editor_opened",
                            "editor_available",
                            "control_clicked"
                          ]
                        },
                        "controlId": {
                          "type": "string"
                        },
                        "timezone": {
                          "type": "string"
                        },
                        "startAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "endAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "delaySeconds": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 86400
                        },
                        "priority": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 100
                        },
                        "maxDisplays": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 100
                        },
                        "cooldownSeconds": {
                          "type": "integer",
                          "minimum": 60,
                          "maximum": 2592000
                        },
                        "actions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "type": {
                                "type": "string",
                                "enum": [
                                  "https",
                                  "navigate",
                                  "dismiss",
                                  "resource",
                                  "download",
                                  "instructions"
                                ]
                              },
                              "label": {
                                "type": "string"
                              },
                              "target": {
                                "type": "string"
                              },
                              "presentation": {
                                "type": "string",
                                "enum": [
                                  "button",
                                  "link"
                                ]
                              },
                              "resource": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "kind": {
                                    "type": "string"
                                  },
                                  "productId": {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  "url": {
                                    "type": "string"
                                  },
                                  "downloadAvailable": {
                                    "type": "boolean"
                                  }
                                },
                                "additionalProperties": true
                              }
                            },
                            "additionalProperties": true
                          },
                          "maxItems": 4
                        },
                        "action": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "type": {
                              "type": "string",
                              "enum": [
                                "https",
                                "navigate",
                                "dismiss",
                                "resource",
                                "download",
                                "instructions"
                              ]
                            },
                            "label": {
                              "type": "string"
                            },
                            "target": {
                              "type": "string"
                            },
                            "presentation": {
                              "type": "string",
                              "enum": [
                                "button",
                                "link"
                              ]
                            },
                            "resource": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "kind": {
                                  "type": "string"
                                },
                                "productId": {
                                  "type": "integer",
                                  "minimum": 1
                                },
                                "url": {
                                  "type": "string"
                                },
                                "downloadAvailable": {
                                  "type": "boolean"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true,
                          "description": "Legacy single-action input; prefer actions for new integrations."
                        },
                        "resourceId": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "const": ""
                            }
                          ]
                        },
                        "linkedProductId": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 1
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "productUrl": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "name",
                        "title",
                        "body",
                        "audience",
                        "trigger",
                        "timezone",
                        "startAt",
                        "endAt",
                        "delaySeconds",
                        "priority",
                        "maxDisplays",
                        "cooldownSeconds"
                      ],
                      "anyOf": [
                        {
                          "required": [
                            "actions"
                          ]
                        },
                        {
                          "required": [
                            "action"
                          ]
                        }
                      ]
                    },
                    "updated_at": {
                      "type": "string",
                      "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 session token",
        "x-access-scope": "marketing.view to read; marketing.manage to write. Effective developer and every assigned product in a notice/reference must be permitted.",
        "x-request-fields": [
          "id: string",
          "expectedVersion: integer",
          "productIds: array",
          "scopeMode: selected | all_integrated",
          "content: 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": [
          "campaign_changed",
          "invalid_product_scope",
          "control_not_allowed",
          "content_not_compatible"
        ],
        "x-source-files": [
          "routes/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "expectedVersion": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "productIds": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "minItems": 1,
                    "maxItems": 100
                  },
                  "scopeMode": {
                    "type": "string",
                    "enum": [
                      "selected",
                      "all_integrated"
                    ]
                  },
                  "content": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "title": {
                        "type": "string"
                      },
                      "body": {
                        "type": "string"
                      },
                      "brand": {
                        "type": "string"
                      },
                      "color": {
                        "type": "string"
                      },
                      "audience": {
                        "type": "string",
                        "enum": [
                          "public",
                          "customers"
                        ]
                      },
                      "noticeType": {
                        "type": "string",
                        "enum": [
                          "announcement",
                          "content",
                          "plugin_update",
                          "download",
                          "promotion"
                        ]
                      },
                      "trigger": {
                        "type": "string",
                        "enum": [
                          "editor_opened",
                          "editor_available",
                          "control_clicked"
                        ]
                      },
                      "controlId": {
                        "type": "string"
                      },
                      "timezone": {
                        "type": "string"
                      },
                      "startAt": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "endAt": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "delaySeconds": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 86400
                      },
                      "priority": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "maxDisplays": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 100
                      },
                      "cooldownSeconds": {
                        "type": "integer",
                        "minimum": 60,
                        "maximum": 2592000
                      },
                      "actions": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "type": {
                              "type": "string",
                              "enum": [
                                "https",
                                "navigate",
                                "dismiss",
                                "resource",
                                "download",
                                "instructions"
                              ]
                            },
                            "label": {
                              "type": "string"
                            },
                            "target": {
                              "type": "string"
                            },
                            "presentation": {
                              "type": "string",
                              "enum": [
                                "button",
                                "link"
                              ]
                            },
                            "resource": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "kind": {
                                  "type": "string"
                                },
                                "productId": {
                                  "type": "integer",
                                  "minimum": 1
                                },
                                "url": {
                                  "type": "string"
                                },
                                "downloadAvailable": {
                                  "type": "boolean"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        },
                        "maxItems": 4
                      },
                      "action": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "https",
                              "navigate",
                              "dismiss",
                              "resource",
                              "download",
                              "instructions"
                            ]
                          },
                          "label": {
                            "type": "string"
                          },
                          "target": {
                            "type": "string"
                          },
                          "presentation": {
                            "type": "string",
                            "enum": [
                              "button",
                              "link"
                            ]
                          },
                          "resource": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "kind": {
                                "type": "string"
                              },
                              "productId": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "url": {
                                "type": "string"
                              },
                              "downloadAvailable": {
                                "type": "boolean"
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "additionalProperties": true,
                        "description": "Legacy single-action input; prefer actions for new integrations."
                      },
                      "resourceId": {
                        "anyOf": [
                          {
                            "type": "string",
                            "format": "uuid"
                          },
                          {
                            "const": ""
                          }
                        ]
                      },
                      "linkedProductId": {
                        "anyOf": [
                          {
                            "type": "integer",
                            "minimum": 1
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "productUrl": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true,
                    "required": [
                      "name",
                      "title",
                      "body",
                      "audience",
                      "trigger",
                      "timezone",
                      "startAt",
                      "endAt",
                      "delaySeconds",
                      "priority",
                      "maxDisplays",
                      "cooldownSeconds"
                    ],
                    "anyOf": [
                      {
                        "required": [
                          "actions"
                        ]
                      },
                      {
                        "required": [
                          "action"
                        ]
                      }
                    ]
                  }
                },
                "additionalProperties": true,
                "required": [
                  "content"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/notices/campaigns/{id}/report": {
      "get": {
        "summary": "Read delivery, action and actual-display counts",
        "description": "A report reconciles stale delivery states. fetched, shown, clicked and dismissed are distinct; fetching is not proof the customer saw the card. Exactly-once display across crashes is not guaranteed.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: states, receipts, actions, fetched.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "states": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "state": {
                            "type": "string"
                          },
                          "count": {
                            "type": "integer",
                            "minimum": 0
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "receipts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "kind": {
                            "type": "string"
                          },
                          "count": {
                            "type": "integer",
                            "minimum": 0
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "actions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "action_id": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string"
                          },
                          "count": {
                            "type": "integer",
                            "minimum": 0
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "fetched": {
                      "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"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "marketing.view to read; marketing.manage to write. Effective developer and every assigned product in a notice/reference must be permitted.",
        "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/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ]
      }
    },
    "/api/developer/notices/campaigns/{id}/state": {
      "post": {
        "summary": "Publish, pause or archive a reviewed notice version",
        "description": "Publishing rechecks enabled channels, scope, references and the end date. product_or_window_disabled includes reason:expired, delivery_disabled or public_disabled, and affected productIds where relevant. A rejected publish does not enable delivery implicitly. Enable the required channels deliberately, save changed dates as a new draft and publish its current expectedVersion. A future start remains scheduled. Pausing/archiving cancels outstanding work. Publishing never schedules a marketing email or changes licensing.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: id, product_id, product_ids, scope_mode, version, state, draft, updated_at.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "product_id": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "product_ids": {
                      "type": "array",
                      "items": {
                        "type": "integer",
                        "minimum": 1
                      }
                    },
                    "scope_mode": {
                      "type": "string"
                    },
                    "version": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "state": {
                      "type": "string",
                      "enum": [
                        "draft",
                        "published",
                        "paused",
                        "archived"
                      ]
                    },
                    "draft": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "title": {
                          "type": "string"
                        },
                        "body": {
                          "type": "string"
                        },
                        "brand": {
                          "type": "string"
                        },
                        "color": {
                          "type": "string"
                        },
                        "audience": {
                          "type": "string",
                          "enum": [
                            "public",
                            "customers"
                          ]
                        },
                        "noticeType": {
                          "type": "string",
                          "enum": [
                            "announcement",
                            "content",
                            "plugin_update",
                            "download",
                            "promotion"
                          ]
                        },
                        "trigger": {
                          "type": "string",
                          "enum": [
                            "editor_opened",
                            "editor_available",
                            "control_clicked"
                          ]
                        },
                        "controlId": {
                          "type": "string"
                        },
                        "timezone": {
                          "type": "string"
                        },
                        "startAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "endAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "delaySeconds": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 86400
                        },
                        "priority": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 100
                        },
                        "maxDisplays": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 100
                        },
                        "cooldownSeconds": {
                          "type": "integer",
                          "minimum": 60,
                          "maximum": 2592000
                        },
                        "actions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "type": {
                                "type": "string",
                                "enum": [
                                  "https",
                                  "navigate",
                                  "dismiss",
                                  "resource",
                                  "download",
                                  "instructions"
                                ]
                              },
                              "label": {
                                "type": "string"
                              },
                              "target": {
                                "type": "string"
                              },
                              "presentation": {
                                "type": "string",
                                "enum": [
                                  "button",
                                  "link"
                                ]
                              },
                              "resource": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "kind": {
                                    "type": "string"
                                  },
                                  "productId": {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  "url": {
                                    "type": "string"
                                  },
                                  "downloadAvailable": {
                                    "type": "boolean"
                                  }
                                },
                                "additionalProperties": true
                              }
                            },
                            "additionalProperties": true
                          },
                          "maxItems": 4
                        },
                        "action": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "type": {
                              "type": "string",
                              "enum": [
                                "https",
                                "navigate",
                                "dismiss",
                                "resource",
                                "download",
                                "instructions"
                              ]
                            },
                            "label": {
                              "type": "string"
                            },
                            "target": {
                              "type": "string"
                            },
                            "presentation": {
                              "type": "string",
                              "enum": [
                                "button",
                                "link"
                              ]
                            },
                            "resource": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "kind": {
                                  "type": "string"
                                },
                                "productId": {
                                  "type": "integer",
                                  "minimum": 1
                                },
                                "url": {
                                  "type": "string"
                                },
                                "downloadAvailable": {
                                  "type": "boolean"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true,
                          "description": "Legacy single-action input; prefer actions for new integrations."
                        },
                        "resourceId": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "const": ""
                            }
                          ]
                        },
                        "linkedProductId": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 1
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "productUrl": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "name",
                        "title",
                        "body",
                        "audience",
                        "trigger",
                        "timezone",
                        "startAt",
                        "endAt",
                        "delaySeconds",
                        "priority",
                        "maxDisplays",
                        "cooldownSeconds"
                      ],
                      "anyOf": [
                        {
                          "required": [
                            "actions"
                          ]
                        },
                        {
                          "required": [
                            "action"
                          ]
                        }
                      ]
                    },
                    "updated_at": {
                      "type": "string",
                      "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 session token",
        "x-access-scope": "marketing.view to read; marketing.manage to write. Effective developer and every assigned product in a notice/reference must be permitted.",
        "x-request-fields": [
          "state: published | paused | archived (required)",
          "expectedVersion: 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-error-codes": [
          "campaign_changed",
          "product_or_window_disabled"
        ],
        "x-source-files": [
          "routes/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "state": {
                    "type": "string",
                    "enum": [
                      "published",
                      "paused",
                      "archived"
                    ]
                  },
                  "expectedVersion": {
                    "type": "integer",
                    "minimum": 1
                  }
                },
                "additionalProperties": true,
                "required": [
                  "state",
                  "expectedVersion"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/notices/companion": {
      "get": {
        "summary": "Download independent notice-companion source",
        "description": "Authenticated source ZIP, not a precompiled plugin or installer. The complete JUCE source package already integrates the maintained companion. Regenerate, rebuild and distribute your actual plugin to update existing binaries.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: application/zip.",
            "content": {
              "application/zip": {
                "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 session token",
        "x-access-scope": "marketing.view to read; marketing.manage to write. Effective developer and every assigned product in a notice/reference must be permitted.",
        "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/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ]
      }
    },
    "/api/developer/notices/products": {
      "get": {
        "summary": "List permitted product notice channels",
        "description": "",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "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"
                      },
                      "enabled": {
                        "anyOf": [
                          {
                            "type": "boolean"
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "public_enabled": {
                        "anyOf": [
                          {
                            "type": "boolean"
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "control_ids": {
                        "anyOf": [
                          {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "navigation_ids": {
                        "anyOf": [
                          {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          {
                            "type": "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 session token",
        "x-access-scope": "marketing.view to read; marketing.manage to write. Effective developer and every assigned product in a notice/reference must be permitted.",
        "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/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ]
      }
    },
    "/api/developer/notices/products/{id}": {
      "put": {
        "summary": "Save the independent product channel and registered host controls",
        "description": "Defaults are disabled. The host must register the same permitted IDs. These controls are unrelated to licensing settings or offline grace.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: product_id, enabled, public_enabled, control_ids, navigation_ids.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "product_id": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "enabled": {
                      "type": "boolean"
                    },
                    "public_enabled": {
                      "type": "boolean"
                    },
                    "control_ids": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "navigation_ids": {
                      "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 session token",
        "x-access-scope": "marketing.view to read; marketing.manage to write. Effective developer and every assigned product in a notice/reference must be permitted.",
        "x-request-fields": [
          "enabled: boolean (required)",
          "publicEnabled: boolean (required)",
          "controlIds: array (required)",
          "navigationIds: 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/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  },
                  "publicEnabled": {
                    "type": "boolean"
                  },
                  "controlIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 32
                  },
                  "navigationIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 32
                  }
                },
                "additionalProperties": true,
                "required": [
                  "enabled",
                  "publicEnabled",
                  "controlIds",
                  "navigationIds"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/notices/products/{id}/content-files": {
      "get": {
        "summary": "List managed files eligible for notice content downloads",
        "description": "Private object keys are omitted. Refresh before selecting a file; a content-file hash identifies this exact managed file rather than an arbitrary external URL.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: review the response schema below.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      },
                      "sha256": {
                        "type": "string"
                      },
                      "sizeBytes": {
                        "anyOf": [
                          {
                            "type": "integer",
                            "minimum": 0
                          },
                          {
                            "type": "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 session token",
        "x-access-scope": "marketing.view to read; marketing.manage to write. Effective developer and every assigned product in a notice/reference must be permitted.",
        "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/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js",
          "services/pluginNoticeContentService.js"
        ]
      }
    },
    "/api/developer/notices/products/{id}/enable": {
      "post": {
        "summary": "Enable notice delivery without replacing existing host registrations",
        "description": "Enables delivery for the permitted product and merges valid host IDs with existing registrations. Each merged list is limited to 32 IDs. publicEnabled:true also enables the public channel; omission or false does not disable an already enabled public channel. Use PUT for deliberate replacement/disable settings. This setup action does not publish a campaign, change licensing or extend offline grace.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: product_id, enabled, public_enabled, control_ids, navigation_ids.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "product_id": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "enabled": {
                      "type": "boolean"
                    },
                    "public_enabled": {
                      "type": "boolean"
                    },
                    "control_ids": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "navigation_ids": {
                      "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 session token",
        "x-access-scope": "marketing.view to read; marketing.manage to write. Effective developer and every assigned product in a notice/reference must be permitted.",
        "x-request-fields": [
          "publicEnabled: boolean",
          "controlIds: array",
          "navigationIds: 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": [
          "invalid_body",
          "invalid_settings",
          "invalid_allowlist",
          "product_not_found"
        ],
        "x-source-files": [
          "routes/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "publicEnabled": {
                    "type": "boolean"
                  },
                  "controlIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 32
                  },
                  "navigationIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 32
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/developer/notices/resources": {
      "get": {
        "summary": "List immutable release/content/download references",
        "description": "Returns at most 200 rows at the requested offset. Team scope covers the resource product and every compatible product.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [
          {
            "name": "resourceId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: review the response schema below.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "product_id": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "kind": {
                        "type": "string",
                        "enum": [
                          "release",
                          "content",
                          "download"
                        ]
                      },
                      "name": {
                        "type": "string"
                      },
                      "version": {
                        "type": "string"
                      },
                      "description": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      },
                      "compatible_product_ids": {
                        "type": "array",
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        }
                      },
                      "state": {
                        "type": "string",
                        "enum": [
                          "published",
                          "archived"
                        ]
                      },
                      "download": {
                        "anyOf": [
                          {
                            "type": "object",
                            "properties": {},
                            "additionalProperties": true
                          },
                          {
                            "type": "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 session token",
        "x-access-scope": "marketing.view to read; marketing.manage to write. Effective developer and every assigned product in a notice/reference must be permitted.",
        "x-request-fields": [
          "query resourceId: string",
          "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-source-files": [
          "routes/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ]
      },
      "post": {
        "summary": "Create an immutable approved content or release reference",
        "description": "A release requires version. Content/download can reference an existing permitted managed file with deliveryMode:download and at least one nonempty instruction set. Use common, windows and mac keys; show the matching OS set, otherwise common, never concatenate sets. Existing IDs cannot be edited: create a new version. HTTPS destinations must pass server validation.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: id, product_id, kind, name, version, description, url, compatible_product_ids, state, download.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "product_id": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "release",
                        "content",
                        "download"
                      ]
                    },
                    "name": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    },
                    "compatible_product_ids": {
                      "type": "array",
                      "items": {
                        "type": "integer",
                        "minimum": 1
                      }
                    },
                    "state": {
                      "type": "string",
                      "enum": [
                        "published",
                        "archived"
                      ]
                    },
                    "download": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {},
                          "additionalProperties": true
                        },
                        {
                          "type": "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 session token",
        "x-access-scope": "marketing.view to read; marketing.manage to write. Effective developer and every assigned product in a notice/reference must be permitted.",
        "x-request-fields": [
          "productId: integer (required)",
          "kind: release | content | download (required)",
          "name: string (required)",
          "version: string",
          "description: string",
          "url: string (required)",
          "compatibleProductIds: array",
          "deliveryMode: reference | download",
          "downloadFileId: string",
          "instructions: object",
          "supportUrl: 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/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "productId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "release",
                      "content",
                      "download"
                    ]
                  },
                  "name": {
                    "type": "string"
                  },
                  "version": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  },
                  "compatibleProductIds": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": 1
                    }
                  },
                  "deliveryMode": {
                    "type": "string",
                    "enum": [
                      "reference",
                      "download"
                    ]
                  },
                  "downloadFileId": {
                    "type": "string"
                  },
                  "instructions": {
                    "type": "object",
                    "properties": {
                      "common": {
                        "type": "string"
                      },
                      "windows": {
                        "type": "string"
                      },
                      "mac": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true
                  },
                  "supportUrl": {
                    "type": "string"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "productId",
                  "kind",
                  "name",
                  "url"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/notices/resources/{id}/archive": {
      "post": {
        "summary": "Archive a reference and cancel outstanding dependent deliveries",
        "description": "Historical records remain; the archived reference cannot be newly published or served.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: id, product_id, kind, name, version, description, url, compatible_product_ids, state, download.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "product_id": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "release",
                        "content",
                        "download"
                      ]
                    },
                    "name": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    },
                    "compatible_product_ids": {
                      "type": "array",
                      "items": {
                        "type": "integer",
                        "minimum": 1
                      }
                    },
                    "state": {
                      "type": "string",
                      "enum": [
                        "published",
                        "archived"
                      ]
                    },
                    "download": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {},
                          "additionalProperties": true
                        },
                        {
                          "type": "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 session token",
        "x-access-scope": "marketing.view to read; marketing.manage to write. Effective developer and every assigned product in a notice/reference must be permitted.",
        "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/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ]
      }
    },
    "/api/developer/notices/schema": {
      "get": {
        "summary": "Read authoring capabilities, branding and companion version",
        "description": "",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: types, triggers, canManage, installerIncluded, contentDownloadsIncluded, deliveryEnabled, packageVersion, branding.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "types": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "triggers": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "canManage": {
                      "type": "boolean"
                    },
                    "installerIncluded": {
                      "const": false
                    },
                    "contentDownloadsIncluded": {
                      "type": "boolean"
                    },
                    "deliveryEnabled": {
                      "type": "boolean"
                    },
                    "packageVersion": {
                      "type": "string"
                    },
                    "branding": {
                      "type": "object",
                      "properties": {
                        "brand": {
                          "type": "string"
                        },
                        "color": {
                          "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 session token",
        "x-access-scope": "marketing.view to read; marketing.manage to write. Effective developer and every assigned product in a notice/reference must be permitted.",
        "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/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ]
      }
    },
    "/api/developer/notifications": {
      "get": {
        "summary": "Read actionable billing, email and product notices for the permitted workspace",
        "description": "Read-only: does not create a billing customer, change cards, reserve spend, dispatch email or send money. notices contains current actionable checks; unavailable names sources that could not be checked. An empty list is not proof of healthy sources when unavailable is nonempty. Source results can be cached for 60 seconds per effective developer, workspace, permission set and product scope; checkedAt is the collection time, not a telemetry guarantee. Successful responses are private,no-store. Read state is kept by the maintained browser client, not written through this endpoint; marking read does not resolve the issue. A workspace-required account notice is generated locally after session discovery and is not a successful response from this endpoint. Historical missing plugin-test evidence alone does not produce a live connection-failure notice. Notices and Activity are separate. Activity contains at most 50 grouped updates from the last 14 days and does not increase the warning count. Durable incident and milestone state is separate from browser-local unread markers. Resolution/retry/deadline fields are informational; reading or marking read never retries work, dismisses an active issue or changes account permissions.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/developer-notices"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: workspaceId, developerId, checkedAt, unavailable, notices, activity, activityWindowDays, activityLimit.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "workspaceId": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "developerId": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "checkedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "unavailable": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "notices": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "severity": {
                            "type": "string",
                            "enum": [
                              "warning",
                              "error"
                            ]
                          },
                          "title": {
                            "type": "string"
                          },
                          "message": {
                            "type": "string"
                          },
                          "href": {
                            "type": "string"
                          },
                          "actionLabel": {
                            "type": "string"
                          },
                          "revision": {
                            "type": "string"
                          },
                          "retryText": {
                            "type": "string"
                          },
                          "resolution": {
                            "type": "string"
                          },
                          "incidentId": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "urgency": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "affected": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "label": {
                                  "type": "string"
                                },
                                "href": {
                                  "type": "string"
                                },
                                "reason": {
                                  "type": "string"
                                },
                                "retryText": {
                                  "type": "string"
                                },
                                "resolution": {
                                  "type": "string"
                                },
                                "nextRetryAt": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "format": "date-time"
                                },
                                "deadlineAt": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "format": "date-time"
                                },
                                "count": {
                                  "type": "number"
                                },
                                "unit": {
                                  "type": "string"
                                }
                              },
                              "additionalProperties": true
                            }
                          }
                        },
                        "additionalProperties": true,
                        "required": [
                          "id",
                          "severity",
                          "title",
                          "message",
                          "href",
                          "actionLabel",
                          "revision"
                        ]
                      }
                    },
                    "activity": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "severity": {
                            "const": "info"
                          },
                          "tone": {
                            "type": "string",
                            "enum": [
                              "info",
                              "success"
                            ]
                          },
                          "category": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "message": {
                            "type": "string"
                          },
                          "href": {
                            "type": "string"
                          },
                          "actionLabel": {
                            "type": "string"
                          },
                          "occurredAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "count": {
                            "type": "number"
                          },
                          "revision": {
                            "type": "string"
                          },
                          "retryText": {
                            "type": "string"
                          },
                          "resolution": {
                            "type": "string"
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "activityWindowDays": {
                      "const": 14
                    },
                    "activityLimit": {
                      "const": 50
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "workspaceId",
                    "developerId",
                    "checkedAt",
                    "unavailable",
                    "notices"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/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 session token",
        "x-access-scope": "workspace.view and active selected-workspace access. Billing and email sources require all-products scope and billing.view/marketing.view respectively. Product notices require products.view and stay assigned-product scoped. Additional sources use existing orders, refunds, customers, serials, domains, payouts, team, API/webhook and partner permissions; private details remain permission-filtered.",
        "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/developerNotificationRoutes.js",
          "services/developerNotificationService.js",
          "services/developerTeamService.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b"
      }
    },
    "/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. serviceAgreement is the effective agreement, while onboarding.serviceOption is a draft selection and onboarding.serviceOptions lists advertised choices. selected:false and active:false do not start service billing; a default Full Store identity is not owner acceptance. Monetary service fields are USD cents, saleFeeBps is basis points and storageBytes is bytes.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/developer-onboarding"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: featureEnabled, entryRoute, serviceAgreement, onboarding.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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, serviceAgreement, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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, serviceAgreement, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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",
          "services/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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, serviceAgreement, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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",
          "services/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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 session token",
        "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",
          "services/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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, serviceAgreement, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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, serviceAgreement, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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",
          "services/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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, serviceAgreement, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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",
          "services/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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 and Licensing + Hosting normalize sellingModels to licensing_only; Full Store uses a supported commerce path. The service option is separate from a customer subscription or launch-path style. Changing the service choice resets pricing acknowledgment unless explicitly confirmed for the current policy. Saving a draft does not activate billing. An active option change requires support review; 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, serviceAgreement, onboarding.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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 | ",
          "serviceOption: full_store | licensing_hosting | licensing_only | ",
          "servicePricingAcknowledged: boolean",
          "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-error-codes": [
          "INVALID_DEVELOPER_SERVICE_OPTION",
          "ACTIVE_SERVICE_OPTION_CHANGE_REQUIRES_REVIEW"
        ],
        "x-source-files": [
          "routes/developerOnboardingV2Routes.js",
          "services/developerOnboardingV2Service.js",
          "services/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.js"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "launchPath": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "enum": [
                      "quick",
                      "fully_branded",
                      null
                    ]
                  },
                  "serviceOption": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "enum": [
                      "full_store",
                      "licensing_hosting",
                      "licensing_only",
                      null
                    ]
                  },
                  "servicePricingAcknowledged": {
                    "type": "boolean"
                  },
                  "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. Choose serviceOption and explicitly confirm servicePricingAcknowledged=true. Full Store has a $20 monthly minimum on its 3% sales fees only. Email/redemption usage and actual provider fees are additional. Licensing + Hosting is $20/month and Licensing is $10/month. Completion records owner pricing acceptance; monthly billing starts with production activation. Non-checkout options use the licensing_only setup path. 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, serviceAgreement, onboarding.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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 | ",
          "serviceOption: full_store | licensing_hosting | licensing_only | ",
          "servicePricingAcknowledged: boolean",
          "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-error-codes": [
          "SERVICE_PRICING_ACK_REQUIRED",
          "SERVICE_OPTION_OWNER_REQUIRED",
          "ACTIVE_SERVICE_OPTION_CHANGE_REQUIRES_REVIEW",
          "INVALID_DEVELOPER_SERVICE_OPTION",
          "LAUNCH_PATH_REQUIRED",
          "SELLING_MODEL_REQUIRED"
        ],
        "x-source-files": [
          "routes/developerOnboardingV2Routes.js",
          "services/developerOnboardingV2Service.js",
          "services/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.js"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "launchPath": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "enum": [
                      "quick",
                      "fully_branded",
                      null
                    ]
                  },
                  "serviceOption": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "enum": [
                      "full_store",
                      "licensing_hosting",
                      "licensing_only",
                      null
                    ]
                  },
                  "servicePricingAcknowledged": {
                    "type": "boolean"
                  },
                  "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, serviceAgreement, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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, serviceAgreement, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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",
          "services/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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, serviceAgreement, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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",
          "services/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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, serviceAgreement, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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, serviceAgreement, onboarding.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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",
          "services/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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, serviceAgreement, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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, serviceAgreement, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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",
          "services/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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, serviceAgreement, onboarding.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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",
          "services/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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, serviceAgreement, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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, serviceAgreement, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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",
          "services/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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, serviceAgreement, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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",
          "services/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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",
                          "headless_api"
                        ]
                      },
                      "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, serviceAgreement, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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 | headless_api (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",
          "services/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "websiteUrl": {
                    "type": "string"
                  },
                  "integrationApproach": {
                    "type": "string",
                    "enum": [
                      "storefront_package",
                      "standalone_pages",
                      "headless_api"
                    ]
                  },
                  "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, serviceAgreement, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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, serviceAgreement, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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",
          "services/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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, serviceAgreement, onboarding.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featureEnabled": {
                      "type": "boolean"
                    },
                    "entryRoute": {
                      "type": "string"
                    },
                    "serviceAgreement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "enum": [
                            "full_store",
                            "licensing_hosting",
                            "licensing_only"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "priceDetail": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyMinimumCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "saleFeeBps": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "minimumBasis": {
                          "type": "string",
                          "enum": [
                            "sales_fees",
                            "soundsync_charges"
                          ],
                          "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                        },
                        "hosting": {
                          "type": "boolean"
                        },
                        "checkout": {
                          "type": "boolean"
                        },
                        "storageBytes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Bytes, not GB. Current service allowances use decimal GB."
                        },
                        "storageLabel": {
                          "type": "string"
                        },
                        "features": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "selected": {
                          "type": "boolean"
                        },
                        "legacy": {
                          "type": "boolean"
                        },
                        "agreementId": {
                          "type": [
                            "integer",
                            "string",
                            "null"
                          ],
                          "minimum": 1,
                          "pattern": "^[1-9][0-9]*$",
                          "description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
                        },
                        "policyVersion": {
                          "type": "string"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "effectiveFrom": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "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."
                        },
                        "serviceOption": {
                          "anyOf": [
                            {
                              "type": "string",
                              "enum": [
                                "full_store",
                                "licensing_hosting",
                                "licensing_only"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "servicePricingAcknowledged": {
                          "type": "boolean"
                        },
                        "servicePolicyVersion": {
                          "type": "string"
                        },
                        "serviceOptions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "enum": [
                                  "full_store",
                                  "licensing_hosting",
                                  "licensing_only"
                                ]
                              },
                              "name": {
                                "type": "string"
                              },
                              "price": {
                                "type": "string"
                              },
                              "priceDetail": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "monthlyFeeCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "monthlyMinimumCents": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "saleFeeBps": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "minimumBasis": {
                                "type": "string",
                                "enum": [
                                  "sales_fees",
                                  "soundsync_charges"
                                ],
                                "description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
                              },
                              "hosting": {
                                "type": "boolean"
                              },
                              "checkout": {
                                "type": "boolean"
                              },
                              "storageBytes": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Bytes, not GB. Current service allowances use decimal GB."
                              },
                              "storageLabel": {
                                "type": "string"
                              },
                              "features": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "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 session token",
        "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/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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",
          "services/developerServiceOptionService.js",
          "public/store/modules/developer/serviceOptions.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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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 session token",
        "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 session token",
        "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}/messages": {
      "post": {
        "summary": "POST /api/developer/partners/{relationshipId}/conversations. Starts a conversation and requires subject plus body/message. To reply to an existing thread, use its thread-specific messages path.",
        "description": "Active compatibility alias of POST /api/developer/partners/{relationshipId}/conversations. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. Starts a conversation and requires subject plus body/message. To reply to an existing thread, use its thread-specific messages path. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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-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}/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 session token",
        "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"
        ]
      },
      "post": {
        "summary": "Read the disabled developer-created external-order response",
        "description": "Returns 410 PARTNER_FULFILLMENT_DISABLED. The developer controller keeps this operation disabled even when the fulfillment capability is enabled; no submitted order or payable statement is created or updated. Authorized historical GET reads remain separate. Use the approved Partner API/portal for external fulfillment and the current statement-record/document tools for reseller reconciliation. A recorded external statement is not a SoundSync-funded payout.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/partner-management"
        },
        "parameters": [
          {
            "name": "relationshipId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "410": {
            "description": "HTTP 410: code, message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "PARTNER_FULFILLMENT_DISABLED"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "partners.view + partners.manage and all-products workspace scope; 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"
        ],
        "deprecated": true
      }
    },
    "/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 session token",
        "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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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 session token",
        "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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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 session token",
        "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 session token",
        "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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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 session token",
        "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"
        ]
      },
      "patch": {
        "summary": "PATCH /api/developer/partners/resellers/{relationshipId}/terms",
        "description": "Active compatibility alias of PATCH /api/developer/partners/resellers/{relationshipId}/terms. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-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/{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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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/product-options": {
      "get": {
        "summary": "List owned products and their partner-assignment/serial-pool eligibility",
        "description": "Authorization eligibility and serial-pool eligibility are separate. Download-only one-time products can use Library redemption codes without enabling native serial licensing. Subscription-only or access-only bundle products require their appropriate fulfillment model; archive and activation settings remain enforced.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/partner-management"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: products.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "products": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "name": {
                            "type": "string"
                          },
                          "product_type": {
                            "type": "string"
                          },
                          "supports_serials": {
                            "type": "boolean"
                          },
                          "requires_activation": {
                            "type": "boolean"
                          },
                          "supports_downloads": {
                            "type": "boolean"
                          },
                          "archived_at": {
                            "anyOf": [
                              {
                                "type": "string",
                                "format": "date-time"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "subscription_product": {
                            "type": "boolean"
                          },
                          "authorization_eligible": {
                            "type": "boolean"
                          },
                          "pool_eligibility": {
                            "type": "object",
                            "properties": {
                              "eligible": {
                                "type": "boolean"
                              },
                              "delivery": {
                                "type": "string",
                                "enum": [
                                  "activation_serial",
                                  "library_redemption"
                                ]
                              },
                              "code": {
                                "type": "string"
                              },
                              "reason": {
                                "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 session token",
        "x-access-scope": "Existing partner workspace permission and all-products scope; only products owned by the effective developer.",
        "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/partnerWorkspaceRoutes.js",
          "services/partnerHubService.js",
          "services/partnerProductSelectionService.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 session token",
        "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/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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires partners.manage.",
        "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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires partners.manage.",
        "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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires partners.manage.",
        "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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires partners.manage.",
        "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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires partners.manage.",
        "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 session token",
        "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-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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires partners.manage.",
        "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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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 session token",
        "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}": {
      "get": {
        "summary": "GET /api/developer/partners/{relationshipId}",
        "description": "Active compatibility alias of GET /api/developer/partners/{relationshipId}. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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}/activity": {
      "get": {
        "summary": "GET /api/developer/partners/{relationshipId}/activity",
        "description": "Active compatibility alias of GET /api/developer/partners/{relationshipId}/activity. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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}/api-health": {
      "get": {
        "summary": "GET /api/developer/partners/{relationshipId}/api-health",
        "description": "Active compatibility alias of GET /api/developer/partners/{relationshipId}/api-health. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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}/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. Returns key metadata, not plaintext tokens. Creation and rotation require the fulfillment capability; revocation remains available to authorized developers when that capability is disabled. These are separate from the always-disabled developer-created external orders and payable-statement writes.",
        "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 session token",
        "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 relationship API key when fulfillment is enabled",
        "description": "Requires the owner-controlled fulfillment capability. Disabled availability returns 410 PARTNER_FULFILLMENT_DISABLED before key creation/rotation. When enabled, creation defaults to test unless environment:live or test_mode/testMode:false is selected; explicit environment takes precedence. scopes and allowed_product_ids/allowedProductIds restrict the credential. Save the returned token privately: it is revealed once. Rotation replaces an active key and revokes the old key in the same transaction; coordinate installed integrations before rotating. This call does not enable the platform capability or process an external payment.",
        "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: api_key, token, reveal_once.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "api_key": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": [
                            "integer",
                            "string"
                          ]
                        },
                        "relationship_id": {
                          "type": [
                            "integer",
                            "string"
                          ]
                        },
                        "key_prefix": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "environment": {
                          "enum": [
                            "live",
                            "test"
                          ]
                        },
                        "scopes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "allowed_product_ids": {
                          "type": "array",
                          "items": {
                            "type": "integer"
                          }
                        },
                        "created_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "revoked_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "token": {
                      "type": "string"
                    },
                    "reveal_once": {
                      "const": true
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "api_key",
                    "token",
                    "reveal_once"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/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 session token",
        "x-access-scope": "partners.view + partners.manage and all-products workspace scope; owned relationship checks apply.",
        "x-request-fields": [
          "name: string",
          "environment: live | test",
          "test_mode: boolean",
          "testMode: boolean",
          "scopes: array",
          "allowed_product_ids: array",
          "allowedProductIds: 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": [
          "PARTNER_FULFILLMENT_DISABLED"
        ],
        "x-source-files": [
          "routes/developerPartnerHubRoutes.js",
          "controllers/partnerHubController.js",
          "services/partnerHubService.js"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "environment": {
                    "enum": [
                      "live",
                      "test"
                    ]
                  },
                  "test_mode": {
                    "type": "boolean"
                  },
                  "testMode": {
                    "type": "boolean"
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "allowed_product_ids": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    }
                  },
                  "allowedProductIds": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    }
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/developer/partners/resellers/{relationshipId}/api-keys/{keyId}/revoke": {
      "post": {
        "summary": "Revoke an existing relationship API key",
        "description": "Revokes an existing key in an owned relationship and returns api_key metadata, never its plaintext token. This safety action is not gated by fulfillment availability and remains available when new key creation is disabled. Unknown/foreign keys return 404 API_KEY_NOT_FOUND. Revocation affects future partner requests; it does not refund payments, delete customer ownership or execute recovery.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/partner-management"
        },
        "parameters": [
          {
            "name": "relationshipId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "keyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: api_key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "api_key": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": [
                            "integer",
                            "string"
                          ]
                        },
                        "relationship_id": {
                          "type": [
                            "integer",
                            "string"
                          ]
                        },
                        "key_prefix": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "environment": {
                          "enum": [
                            "live",
                            "test"
                          ]
                        },
                        "scopes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "allowed_product_ids": {
                          "type": "array",
                          "items": {
                            "type": "integer"
                          }
                        },
                        "created_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "revoked_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "api_key"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "partners.view + partners.manage and all-products workspace scope; 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}/api-keys/{keyId}/rotate": {
      "post": {
        "summary": "Rotate a relationship API key when fulfillment is enabled",
        "description": "Requires the owner-controlled fulfillment capability. Disabled availability returns 410 PARTNER_FULFILLMENT_DISABLED before key creation/rotation. When enabled, creation defaults to test unless environment:live or test_mode/testMode:false is selected; explicit environment takes precedence. scopes and allowed_product_ids/allowedProductIds restrict the credential. Save the returned token privately: it is revealed once. Rotation replaces an active key and revokes the old key in the same transaction; coordinate installed integrations before rotating. This call does not enable the platform capability or process an external payment.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/partner-management"
        },
        "parameters": [
          {
            "name": "relationshipId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "keyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: api_key, token, reveal_once.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "api_key": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": [
                            "integer",
                            "string"
                          ]
                        },
                        "relationship_id": {
                          "type": [
                            "integer",
                            "string"
                          ]
                        },
                        "key_prefix": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "environment": {
                          "enum": [
                            "live",
                            "test"
                          ]
                        },
                        "scopes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "allowed_product_ids": {
                          "type": "array",
                          "items": {
                            "type": "integer"
                          }
                        },
                        "created_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "revoked_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    },
                    "token": {
                      "type": "string"
                    },
                    "reveal_once": {
                      "const": true
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "api_key",
                    "token",
                    "reveal_once"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/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 session token",
        "x-access-scope": "partners.view + partners.manage and all-products workspace scope; 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-error-codes": [
          "PARTNER_FULFILLMENT_DISABLED"
        ],
        "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 session token",
        "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 session token",
        "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 session token",
        "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": {
      "get": {
        "summary": "GET /api/developer/partners/{relationshipId}/conversations",
        "description": "Active compatibility alias of GET /api/developer/partners/{relationshipId}/conversations. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": "POST /api/developer/partners/{relationshipId}/conversations",
        "description": "Active compatibility alias of POST /api/developer/partners/{relationshipId}/conversations. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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-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/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 session token",
        "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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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}/customers": {
      "get": {
        "summary": "GET /api/developer/partners/{relationshipId}/customers",
        "description": "Active compatibility alias of GET /api/developer/partners/{relationshipId}/customers. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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}/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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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 session token",
        "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}/financials": {
      "get": {
        "summary": "GET /api/developer/partners/{relationshipId}/financials",
        "description": "Active compatibility alias of GET /api/developer/partners/{relationshipId}/financials. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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 session token",
        "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}/messages": {
      "post": {
        "summary": "POST /api/developer/partners/{relationshipId}/conversations. Starts a conversation and requires subject plus body/message. To reply to an existing thread, use its thread-specific messages path.",
        "description": "Active compatibility alias of POST /api/developer/partners/{relationshipId}/conversations. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. Starts a conversation and requires subject plus body/message. To reply to an existing thread, use its thread-specific messages path. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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-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/resellers/{relationshipId}/orders": {
      "get": {
        "summary": "GET /api/developer/partners/{relationshipId}/orders",
        "description": "Active compatibility alias of GET /api/developer/partners/{relationshipId}/orders. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": "Read the disabled developer-created external-order response",
        "description": "Returns 410 PARTNER_FULFILLMENT_DISABLED. The developer controller keeps this operation disabled even when the fulfillment capability is enabled; no submitted order or payable statement is created or updated. Authorized historical GET reads remain separate. Use the approved Partner API/portal for external fulfillment and the current statement-record/document tools for reseller reconciliation. A recorded external statement is not a SoundSync-funded payout.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/partner-management"
        },
        "parameters": [
          {
            "name": "relationshipId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "410": {
            "description": "HTTP 410: code, message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "PARTNER_FULFILLMENT_DISABLED"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "partners.view + partners.manage and all-products workspace scope; 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"
        ],
        "deprecated": true
      }
    },
    "/api/developer/partners/resellers/{relationshipId}/overview": {
      "get": {
        "summary": "GET /api/developer/partners/{relationshipId}/overview",
        "description": "Active compatibility alias of GET /api/developer/partners/{relationshipId}/overview. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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}/pause": {
      "post": {
        "summary": "POST /api/developer/partners/{relationshipId}/pause",
        "description": "Active compatibility alias of POST /api/developer/partners/{relationshipId}/pause. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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/resellers/{relationshipId}/products": {
      "get": {
        "summary": "GET /api/developer/partners/{relationshipId}/products",
        "description": "Active compatibility alias of GET /api/developer/partners/{relationshipId}/products. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": "POST /api/developer/partners/{relationshipId}/products/assign",
        "description": "Active compatibility alias of POST /api/developer/partners/{relationshipId}/products/assign. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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-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/resellers/{relationshipId}/products/{relationshipProductId}": {
      "delete": {
        "summary": "DELETE /api/developer/partners/{relationshipId}/products/{assignmentId}. relationshipProductId is the same saved assignment ID called assignmentId in the preferred path, not a catalog product ID.",
        "description": "Active compatibility alias of DELETE /api/developer/partners/{relationshipId}/products/{assignmentId}. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. relationshipProductId is the same saved assignment ID called assignmentId in the preferred path, not a catalog product ID. 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": "relationshipProductId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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": "PATCH /api/developer/partners/{relationshipId}/products/{assignmentId}. relationshipProductId is the same saved assignment ID called assignmentId in the preferred path, not a catalog product ID.",
        "description": "Active compatibility alias of PATCH /api/developer/partners/{relationshipId}/products/{assignmentId}. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. relationshipProductId is the same saved assignment ID called assignmentId in the preferred path, not a catalog product ID. 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": "relationshipProductId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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-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/resellers/{relationshipId}/products/assign": {
      "post": {
        "summary": "POST /api/developer/partners/{relationshipId}/products/assign",
        "description": "Active compatibility alias of POST /api/developer/partners/{relationshipId}/products/assign. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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-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/resellers/{relationshipId}/resume": {
      "post": {
        "summary": "POST /api/developer/partners/{relationshipId}/resume",
        "description": "Active compatibility alias of POST /api/developer/partners/{relationshipId}/resume. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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/resellers/{relationshipId}/serials": {
      "get": {
        "summary": "GET /api/developer/partners/{relationshipId}/serials",
        "description": "Active compatibility alias of GET /api/developer/partners/{relationshipId}/serials. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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}/serials/{poolId}/export": {
      "get": {
        "summary": "GET /api/developer/partners/{relationshipId}/serials/{poolId}/export",
        "description": "Active compatibility alias of GET /api/developer/partners/{relationshipId}/serials/{poolId}/export. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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/resellers/{relationshipId}/serials/allocate": {
      "post": {
        "summary": "POST /api/developer/partners/{relationshipId}/serials/allocate",
        "description": "Active compatibility alias of POST /api/developer/partners/{relationshipId}/serials/allocate. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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-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/resellers/{relationshipId}/settings": {
      "get": {
        "summary": "GET /api/developer/partners/{relationshipId}/settings",
        "description": "Active compatibility alias of GET /api/developer/partners/{relationshipId}/settings. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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"
        ]
      },
      "patch": {
        "summary": "PATCH /api/developer/partners/resellers/{relationshipId}/terms",
        "description": "Active compatibility alias of PATCH /api/developer/partners/resellers/{relationshipId}/terms. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-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}/statement-records": {
      "post": {
        "summary": "Record an actual externally supplied reseller statement",
        "description": "Amounts are major currency units with at most two decimals, not cents. Period end is exclusive. A positive received payment requires payment_date and cannot exceed due. Duplicate relationship/period/currency returns 409. Blocked accounts/relationships reject writes; paused relationships can reconcile. Recording a statement sends no money.",
        "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: statement.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "statement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "relationship_id": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "developer_id": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "partner_id": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "period_start": {
                          "type": "string"
                        },
                        "period_end": {
                          "type": "string"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "gross_reported_sales_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "expected_payable_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "payment_received_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "outstanding_balance_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "status": {
                          "type": "string"
                        },
                        "record_source": {
                          "type": "string"
                        },
                        "record_details": {
                          "type": "object",
                          "properties": {
                            "reference": {
                              "type": "string"
                            },
                            "notes": {
                              "type": "string"
                            },
                            "payment_date": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "document": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "bytes": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "type": {
                                  "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"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "Developer partners.view with all-products scope; writes additionally partners.manage. Partner views require active eligible reseller membership and the relevant relationship.",
        "x-request-fields": [
          "period_start: string (required)",
          "period_end: string (required)",
          "currency: string",
          "reference: string (required)",
          "notes: string",
          "reported_sales: string,number (required)",
          "amount_due: string,number (required)",
          "payment_received: string,number (required)",
          "payment_date: 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/partnerWorkspaceRoutes.js",
          "services/partnerWorkspaceService.js",
          "services/partnerStatementDocumentService.js",
          "services/partnerStatementShape.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "period_start": {
                    "type": "string"
                  },
                  "period_end": {
                    "type": "string"
                  },
                  "currency": {
                    "type": "string"
                  },
                  "reference": {
                    "type": "string"
                  },
                  "notes": {
                    "type": "string"
                  },
                  "reported_sales": {
                    "type": [
                      "string",
                      "number"
                    ]
                  },
                  "amount_due": {
                    "type": [
                      "string",
                      "number"
                    ]
                  },
                  "payment_received": {
                    "type": [
                      "string",
                      "number"
                    ]
                  },
                  "payment_date": {
                    "type": "string"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "period_start",
                  "period_end",
                  "reference",
                  "reported_sales",
                  "amount_due",
                  "payment_received"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/partners/resellers/{relationshipId}/statement-records/{statementId}/document": {
      "get": {
        "summary": "Download the current relationship-scoped private statement document",
        "description": "Streams the current document with its actual type and Content-Disposition filename; responses are private/no-store. A missing file needs reattachment, while transient storage failure can be retried. Keep financial and personal information out of public screenshots.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/partner-management"
        },
        "parameters": [
          {
            "name": "relationshipId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "statementId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: application/octet-stream.",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
                "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 session token",
        "x-access-scope": "Developer partners.view with all-products scope; writes additionally partners.manage. Partner views require active eligible reseller membership and the relevant relationship.",
        "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/partnerWorkspaceRoutes.js",
          "services/partnerWorkspaceService.js",
          "services/partnerStatementDocumentService.js",
          "services/partnerStatementShape.js"
        ]
      },
      "post": {
        "summary": "Attach a private reseller statement document",
        "description": "One PDF, CSV or XLSX file, at most 5 MB. Requires configured private storage. Scope is checked before upload and again after storage. Replacements retain prior document history; private storage keys are not public response fields.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/partner-management"
        },
        "parameters": [
          {
            "name": "relationshipId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "statementId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: statement.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "statement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "relationship_id": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "developer_id": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "partner_id": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "period_start": {
                          "type": "string"
                        },
                        "period_end": {
                          "type": "string"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "gross_reported_sales_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "expected_payable_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "payment_received_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "outstanding_balance_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "status": {
                          "type": "string"
                        },
                        "record_source": {
                          "type": "string"
                        },
                        "record_details": {
                          "type": "object",
                          "properties": {
                            "reference": {
                              "type": "string"
                            },
                            "notes": {
                              "type": "string"
                            },
                            "payment_date": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "document": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "bytes": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "type": {
                                  "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"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "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 session token",
        "x-access-scope": "Developer partners.view with all-products scope; writes additionally partners.manage. Partner views require active eligible reseller membership and the relevant relationship.",
        "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/partnerWorkspaceRoutes.js",
          "services/partnerWorkspaceService.js",
          "services/partnerStatementDocumentService.js",
          "services/partnerStatementShape.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "file"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/partners/resellers/{relationshipId}/statement-records/{statementId}/payment": {
      "patch": {
        "summary": "Record cumulative external payment received",
        "description": "Send cumulative major-unit payment, no lower than previously recorded and no higher than due. Positive payment needs a date. Disputed/written-off review status is preserved. This records receipt outside SoundSync, not a payout request.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/partner-management"
        },
        "parameters": [
          {
            "name": "relationshipId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "statementId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: statement.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "statement": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "relationship_id": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "developer_id": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "partner_id": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "period_start": {
                          "type": "string"
                        },
                        "period_end": {
                          "type": "string"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "gross_reported_sales_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "expected_payable_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "payment_received_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "outstanding_balance_cents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "status": {
                          "type": "string"
                        },
                        "record_source": {
                          "type": "string"
                        },
                        "record_details": {
                          "type": "object",
                          "properties": {
                            "reference": {
                              "type": "string"
                            },
                            "notes": {
                              "type": "string"
                            },
                            "payment_date": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "document": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "bytes": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "type": {
                                  "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"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "Developer partners.view with all-products scope; writes additionally partners.manage. Partner views require active eligible reseller membership and the relevant relationship.",
        "x-request-fields": [
          "payment_received: string,number (required)",
          "payment_date: 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/partnerWorkspaceRoutes.js",
          "services/partnerWorkspaceService.js",
          "services/partnerStatementDocumentService.js",
          "services/partnerStatementShape.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "payment_received": {
                    "type": [
                      "string",
                      "number"
                    ]
                  },
                  "payment_date": {
                    "type": "string"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "payment_received"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/partners/resellers/{relationshipId}/statements": {
      "get": {
        "summary": "GET /api/developer/partners/{relationshipId}/statements",
        "description": "Active compatibility alias of GET /api/developer/partners/{relationshipId}/statements. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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}/statements/{statementId}": {
      "patch": {
        "summary": "Read the disabled payable-statement update response",
        "description": "Returns 410 PARTNER_FULFILLMENT_DISABLED. The developer controller keeps this operation disabled even when the fulfillment capability is enabled; no submitted order or payable statement is created or updated. Authorized historical GET reads remain separate. Use the approved Partner API/portal for external fulfillment and the current statement-record/document tools for reseller reconciliation. A recorded external statement is not a SoundSync-funded payout.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/partner-management"
        },
        "parameters": [
          {
            "name": "relationshipId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "statementId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "410": {
            "description": "HTTP 410: code, message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "PARTNER_FULFILLMENT_DISABLED"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "partners.view + partners.manage and all-products workspace scope; 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"
        ],
        "deprecated": true
      }
    },
    "/api/developer/partners/resellers/{relationshipId}/statements/generate": {
      "post": {
        "summary": "Read the disabled payable-statement generation response",
        "description": "Returns 410 PARTNER_FULFILLMENT_DISABLED. The developer controller keeps this operation disabled even when the fulfillment capability is enabled; no submitted order or payable statement is created or updated. Authorized historical GET reads remain separate. Use the approved Partner API/portal for external fulfillment and the current statement-record/document tools for reseller reconciliation. A recorded external statement is not a SoundSync-funded payout.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/partner-management"
        },
        "parameters": [
          {
            "name": "relationshipId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "410": {
            "description": "HTTP 410: code, message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "PARTNER_FULFILLMENT_DISABLED"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "partners.view + partners.manage and all-products workspace scope; 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"
        ],
        "deprecated": true
      }
    },
    "/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 session token",
        "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 session token",
        "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 session token",
        "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",
          "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 session token",
        "x-access-scope": "partners.view and all-products workspace scope.",
        "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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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",
          "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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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",
          "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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires partners.manage.",
        "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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires partners.manage.",
        "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 session token",
        "x-access-scope": "partners.view and all-products workspace scope. Also requires 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",
          "services/partnerWooCommerceService.js"
        ]
      }
    },
    "/api/developer/partners/resellers/{relationshipId}/workspace": {
      "get": {
        "summary": "Read scoped inventory, sales estimates and recorded statements",
        "description": "UTC date filters, zero-based page and 25 sales rows per page; follow has_more. Unused licenses are inventory. Redemptions are estimates, linked reported lines are counted separately, currencies are not added together and statements do not prove a SoundSync transfer.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/partner-management"
        },
        "parameters": [
          {
            "name": "relationshipId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "end",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "estimated",
                "reported"
              ]
            }
          },
          {
            "name": "product_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "pool_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "relationship_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: can_record_statements, relationships, filters, sales, has_more, page, summary, daily, pools, products, statements, basis.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "can_record_statements": {
                      "type": "boolean"
                    },
                    "relationships": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "filters": {
                      "type": "object",
                      "properties": {},
                      "additionalProperties": true
                    },
                    "sales": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "page": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "summary": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "daily": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "pools": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "products": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "statements": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "relationship_id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "developer_id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "partner_id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "period_start": {
                            "type": "string"
                          },
                          "period_end": {
                            "type": "string"
                          },
                          "currency": {
                            "type": "string"
                          },
                          "gross_reported_sales_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "expected_payable_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "payment_received_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "outstanding_balance_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "status": {
                            "type": "string"
                          },
                          "record_source": {
                            "type": "string"
                          },
                          "record_details": {
                            "type": "object",
                            "properties": {
                              "reference": {
                                "type": "string"
                              },
                              "notes": {
                                "type": "string"
                              },
                              "payment_date": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "document": {
                                "type": "object",
                                "properties": {
                                  "name": {
                                    "type": "string"
                                  },
                                  "bytes": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "type": {
                                    "type": "string"
                                  }
                                },
                                "additionalProperties": true
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "basis": {
                      "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 session token",
        "x-access-scope": "Developer partners.view with all-products scope; writes additionally partners.manage. Partner views require active eligible reseller membership and the relevant relationship.",
        "x-request-fields": [
          "query start: string",
          "query end: string",
          "query page: integer",
          "query kind: string",
          "query product_id: integer",
          "query pool_id: integer",
          "query relationship_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/partnerWorkspaceRoutes.js",
          "services/partnerWorkspaceService.js",
          "services/partnerStatementDocumentService.js",
          "services/partnerStatementShape.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 session token",
        "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 session token",
        "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/workspace": {
      "get": {
        "summary": "Read scoped inventory, sales estimates and recorded statements",
        "description": "UTC date filters, zero-based page and 25 sales rows per page; follow has_more. Unused licenses are inventory. Redemptions are estimates, linked reported lines are counted separately, currencies are not added together and statements do not prove a SoundSync transfer.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/partner-management"
        },
        "parameters": [
          {
            "name": "start",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "end",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "estimated",
                "reported"
              ]
            }
          },
          {
            "name": "product_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "pool_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "relationship_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: can_record_statements, relationships, filters, sales, has_more, page, summary, daily, pools, products, statements, basis.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "can_record_statements": {
                      "type": "boolean"
                    },
                    "relationships": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "filters": {
                      "type": "object",
                      "properties": {},
                      "additionalProperties": true
                    },
                    "sales": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "page": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "summary": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "daily": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "pools": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "products": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "statements": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "relationship_id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "developer_id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "partner_id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "period_start": {
                            "type": "string"
                          },
                          "period_end": {
                            "type": "string"
                          },
                          "currency": {
                            "type": "string"
                          },
                          "gross_reported_sales_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "expected_payable_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "payment_received_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "outstanding_balance_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "status": {
                            "type": "string"
                          },
                          "record_source": {
                            "type": "string"
                          },
                          "record_details": {
                            "type": "object",
                            "properties": {
                              "reference": {
                                "type": "string"
                              },
                              "notes": {
                                "type": "string"
                              },
                              "payment_date": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "document": {
                                "type": "object",
                                "properties": {
                                  "name": {
                                    "type": "string"
                                  },
                                  "bytes": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "type": {
                                    "type": "string"
                                  }
                                },
                                "additionalProperties": true
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "basis": {
                      "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 session token",
        "x-access-scope": "Developer partners.view with all-products scope; writes additionally partners.manage. Partner views require active eligible reseller membership and the relevant relationship.",
        "x-request-fields": [
          "query start: string",
          "query end: string",
          "query page: integer",
          "query kind: string",
          "query product_id: integer",
          "query pool_id: integer",
          "query relationship_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/partnerWorkspaceRoutes.js",
          "services/partnerWorkspaceService.js",
          "services/partnerStatementDocumentService.js",
          "services/partnerStatementShape.js"
        ]
      }
    },
    "/api/developer/payouts/adjustments-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/adjustments-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/adjustments-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "INVALID_ALLOCATION_STATE",
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/payouts/balance": {
      "get": {
        "summary": "GET /api/developer/settlements/balance",
        "description": "Active compatibility alias of GET /api/developer/settlements/balance. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. Can initialize a local settlement account, recalculate balances and refresh a configured Stripe Connect account. Not a zero-write uptime probe. payout_ready is an account/destination status, not approval to send, a guaranteed net amount or confirmed bank receipt. No transfer or automatic-execution setting is changed.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/billing"
        },
        "parameters": [
          {
            "name": "currency",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "usd"
            }
          },
          {
            "name": "environment",
            "in": "query",
            "schema": {
              "enum": [
                "live",
                "test"
              ],
              "default": "live"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "billing.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/developerSettlementRoutes.js",
          "services/payoutSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/payouts/bank-payouts": {
      "get": {
        "summary": "GET /api/developer/settlements/bank-payouts",
        "description": "Active compatibility alias of GET /api/developer/settlements/bank-payouts. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/connectPayoutService.js"
        ]
      }
    },
    "/api/developer/payouts/batches": {
      "get": {
        "summary": "GET /api/developer/settlements/batches",
        "description": "Active compatibility alias of GET /api/developer/settlements/batches. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary.",
        "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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "billing.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/developerSettlementRoutes.js",
          "services/payoutSettlementService.js"
        ]
      }
    },
    "/api/developer/payouts/connect-session": {
      "post": {
        "summary": "POST /api/developer/settlements/connect-session",
        "description": "Active compatibility alias of POST /api/developer/settlements/connect-session. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/billing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "billing.view and all-products workspace scope; effective developer ownership. Workspace owner only for this setup 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": [
          {
            "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/payouts/earnings/adjustments-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/adjustments-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/adjustments-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "INVALID_ALLOCATION_STATE",
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/payouts/earnings/recovery/cases": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/cases",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/cases. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "MOR_RECOVERY_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/payouts/earnings/recovery/cases/{id}": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/cases/{id}",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/cases/{id}. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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/payouts/earnings/recovery/offsets": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/offsets",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/offsets. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/payouts/earnings/recovery/reserve": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/reserve",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/reserve. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "MOR_RECOVERY_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/payouts/earnings/recovery/statements": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/statements",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/statements. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/payouts/earnings/recovery/summary": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/summary",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/summary. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/payouts/earnings/settlements-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/settlements-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/settlements-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "INVALID_ALLOCATION_STATE",
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/payouts/earnings/statements-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/statements-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/statements-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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 Eastern calendar 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": "See the linked operation reference for the response contract.",
            "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",
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "period_start": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "period_end": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "marketing_email_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "redemption_overage_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_adjustment_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "developer_service_fee_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "provider_processing_fees_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "non_sale_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_qualifying_basis": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "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": "AccountSession",
        "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": [
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/payouts/earnings/summary-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/summary-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/summary-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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 Eastern calendar 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": "See the linked operation reference for the response contract.",
            "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",
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "period_start": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "period_end": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "marketing_email_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "redemption_overage_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_adjustment_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "developer_service_fee_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "provider_processing_fees_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "non_sale_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_qualifying_basis": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "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": "AccountSession",
        "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": [
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/payouts/earnings/transactions-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/transactions-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/transactions-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "INVALID_ALLOCATION_STATE",
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/payouts/history": {
      "get": {
        "summary": "GET /api/developer/settlements/history",
        "description": "Active compatibility alias of GET /api/developer/settlements/history. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. Transfer payout_fee records distinguish the original deduction, actual provider fee, prior adjustment, estimated cross-border component and FX quote/settlement. Pending or unclaimed payment is not bank receipt; unreserved fee adjustments can change a later payout.",
        "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": "See the linked operation reference for the response contract.",
            "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
                                },
                                "provider": {
                                  "type": "string"
                                },
                                "payout_fee": {
                                  "anyOf": [
                                    {
                                      "type": "object",
                                      "properties": {
                                        "feeCents": {
                                          "type": "integer",
                                          "minimum": 0
                                        },
                                        "actualFeeCents": {
                                          "anyOf": [
                                            {
                                              "type": "integer",
                                              "minimum": 0
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        },
                                        "adjustmentCents": {
                                          "type": "integer"
                                        },
                                        "differenceCents": {
                                          "anyOf": [
                                            {
                                              "type": "integer"
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        },
                                        "status": {
                                          "type": "string"
                                        },
                                        "feeComponents": {
                                          "type": "array",
                                          "items": {
                                            "type": "object",
                                            "properties": {
                                              "id": {
                                                "type": "string"
                                              },
                                              "kind": {
                                                "type": "string"
                                              },
                                              "basis": {
                                                "type": "string"
                                              },
                                              "amountCents": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "additionalProperties": true
                                          }
                                        },
                                        "crossBorderEstimated": {
                                          "type": "boolean"
                                        },
                                        "crossBorderFeeCents": {
                                          "type": "integer",
                                          "minimum": 0
                                        },
                                        "crossBorderEstimateBasisPoints": {
                                          "anyOf": [
                                            {
                                              "type": "integer",
                                              "minimum": 0
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        },
                                        "fx": {
                                          "anyOf": [
                                            {
                                              "type": "object",
                                              "properties": {
                                                "currency": {
                                                  "type": "string"
                                                },
                                                "localNetMinor": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "actualLocalNetMinor": {
                                                  "anyOf": [
                                                    {
                                                      "type": "integer",
                                                      "minimum": 0
                                                    },
                                                    {
                                                      "type": "null"
                                                    }
                                                  ]
                                                },
                                                "conversionFeeCents": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "actualExchangeRate": {
                                                  "type": "string"
                                                },
                                                "quote": {
                                                  "type": "object",
                                                  "properties": {
                                                    "id": {
                                                      "type": "string"
                                                    },
                                                    "exchangeRate": {
                                                      "type": "string"
                                                    },
                                                    "expiresAt": {
                                                      "type": "string",
                                                      "format": "date-time"
                                                    }
                                                  },
                                                  "additionalProperties": true
                                                },
                                                "settlementVerified": {
                                                  "type": "boolean"
                                                }
                                              },
                                              "additionalProperties": true
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        }
                                      },
                                      "additionalProperties": true
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "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
                      }
                    },
                    "pendingFeeAdjustmentCents": {
                      "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/payoutHistoryReportingService.js",
          "services/revenueReportingScope.js",
          "services/developerPayoutFeeDisclosure.js"
        ]
      }
    },
    "/api/developer/payouts/history/export.csv": {
      "get": {
        "summary": "GET /api/developer/settlements/history/export.csv",
        "description": "Active compatibility alias of GET /api/developer/settlements/history/export.csv. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. The 28 columns, in order, are: Batch, Currency, First sale UTC, Last sale UTC, Scheduled run, Batch earnings cents, Batch status, Invoice offset cents, Transfer reference, Net payout cents, Transfer status, Bank reference, Bank status, Original payout fee deduction cents, Actual payout fee cents, Prior fee adjustment cents, Fee status, Cross-border fee estimated, Cross-border estimate cents included, Cross-border estimate basis points, Quoted FX cost USD cents, Recorded exchange rate, Local payout currency, Recorded local net minor units, FX quote expiry UTC, Conversion status, Fee difference cents, Reconciliation status. Net payout cents is the recorded transfer amount, not gross sale proceeds or guaranteed bank receipt. Actual fee and reconciliation fields can be unavailable until the provider record exists; an empty value is not a confirmed zero. Quoted FX cost is already included in its quoted conversion, not an instruction to subtract it twice. Cross-border estimate cents included is already part of the original deduction. Current accounting is USD; Recorded local net minor units instead uses Local payout currency. Conversion status is confirmed only for a verified settlement, expired_quote for an expired or imminent-expiry quote, unavailable for missing/invalid quote expiry, and quoted for a quote outside that expiry boundary. No FX record leaves this column empty. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/payoutHistoryReportingService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/payouts/ledger": {
      "get": {
        "summary": "GET /api/developer/settlements/ledger",
        "description": "Active compatibility alias of GET /api/developer/settlements/ledger. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary.",
        "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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "billing.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/developerSettlementRoutes.js",
          "services/payoutSettlementService.js"
        ]
      }
    },
    "/api/developer/payouts/payout-email/send-code": {
      "post": {
        "summary": "Send a private verification code to the proposed PayPal payout email",
        "description": "Active compatibility alias of POST /api/developer/settlements/payout-email/send-code. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. Eight-digit code, fifteen-minute expiry, one-minute resend cooldown and five sends per hour. Sends a transactional email. It does not change the active destination or prove PayPal eligibility. verification:null means the delivery result no longer matches an active request, for example because the provider was switched during sending. Do not mark that email verified or silently resend; reload the saved destination and verification state.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/payout-setup"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: verification.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verification": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "email": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string",
                              "enum": [
                                "pending",
                                "verified",
                                "locked",
                                "expired",
                                "delivery_failed"
                              ]
                            },
                            "expiresAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "resendAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "additionalProperties": true
                        },
                        {
                          "type": "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"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "billing.view, all-products workspace scope and workspace owner. These are destination setup operations, not payment approval or sending.",
        "x-request-fields": [
          "email: string (required)",
          "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": [
          "INVALID_PAYPAL_EMAIL",
          "PAYOUT_EMAIL_NOT_VERIFIED",
          "PAYPAL_COUNTRY_UNSUPPORTED",
          "PAYOUT_EMAIL_COOLDOWN",
          "PAYOUT_EMAIL_RATE_LIMIT",
          "PAYOUT_EMAIL_DELIVERY_FAILED"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "services/developerPayoutDestinationService.js",
          "services/developerPayoutEmailVerificationService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 127,
                    "pattern": "^[\\x21-\\x7e]+$"
                  },
                  "environment": {
                    "type": "string",
                    "enum": [
                      "test",
                      "live"
                    ]
                  }
                },
                "additionalProperties": true,
                "required": [
                  "email"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/payouts/payout-email/verify": {
      "post": {
        "summary": "Verify the proposed PayPal payout email before saving it",
        "description": "Active compatibility alias of POST /api/developer/settlements/payout-email/verify. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. Five failed attempts lock this code. A successful verification does not save the payout method: complete payout-method separately.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/payout-setup"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: verification.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verification": {
                      "type": "object",
                      "properties": {
                        "email": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "verified",
                            "locked",
                            "expired",
                            "delivery_failed"
                          ]
                        },
                        "expiresAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "resendAt": {
                          "type": "string",
                          "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"
                }
              }
            }
          },
          "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 session token",
        "x-access-scope": "billing.view, all-products workspace scope and workspace owner. These are destination setup operations, not payment approval or sending.",
        "x-request-fields": [
          "email: string (required)",
          "code: string (required)",
          "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": [
          "INVALID_PAYPAL_EMAIL",
          "PAYOUT_EMAIL_CODE_EXPIRED",
          "PAYOUT_EMAIL_CODE_LOCKED",
          "PAYOUT_EMAIL_CODE_INVALID"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "services/developerPayoutDestinationService.js",
          "services/developerPayoutEmailVerificationService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 127,
                    "pattern": "^[\\x21-\\x7e]+$"
                  },
                  "code": {
                    "type": "string",
                    "pattern": "^[0-9]{8}$"
                  },
                  "environment": {
                    "type": "string",
                    "enum": [
                      "test",
                      "live"
                    ]
                  }
                },
                "additionalProperties": true,
                "required": [
                  "email",
                  "code"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/payouts/payout-method": {
      "post": {
        "summary": "Select one Stripe or PayPal developer payout destination",
        "description": "Active compatibility alias of POST /api/developer/settlements/payout-method. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. For PayPal, verify the SoundSync account and payout email first, provide the registered PayPal country, and confirm account ownership/ability to receive USD. paypalEmail takes precedence over the email alias; an existing saved PayPal email may be reused when neither is sent. Confirmation must be true. Changing a destination can impose a 24-hour wait. In-progress payments block provider switching. PayPal Payouts is approved in production; recipient eligibility, provider requirements and funding still apply. Inbox verification and destination saving do not send money or establish a completed payout. Stripe local settlement does not change USD accounting.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/payout-setup"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: provider, currency, environment, connection.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "provider": {
                      "type": "string",
                      "enum": [
                        "stripe",
                        "paypal"
                      ]
                    },
                    "currency": {
                      "const": "usd"
                    },
                    "environment": {
                      "type": "string"
                    },
                    "connection": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {},
                          "additionalProperties": true
                        },
                        {
                          "type": "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 session token",
        "x-access-scope": "billing.view, all-products workspace scope and workspace owner. These are destination setup operations, not payment approval or sending.",
        "x-request-fields": [
          "provider: stripe | paypal (required)",
          "environment: test | live",
          "paypalEmail: string",
          "email: string. Supported alias for paypalEmail.",
          "paypalAccountCountry: string",
          "confirmPayPalAccount: 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": [
          "PAYPAL_ACCOUNT_CONFIRMATION_REQUIRED",
          "PAYPAL_EMAIL_VERIFICATION_REQUIRED",
          "PAYPAL_ACCOUNT_COUNTRY_REQUIRED",
          "PAYOUT_EMAIL_NOT_VERIFIED",
          "PAYPAL_COUNTRY_UNSUPPORTED",
          "PAYPAL_PAYOUTS_DISABLED",
          "PAYOUT_IN_PROGRESS",
          "STRIPE_USD_PAYOUT_COUNTRY_UNAVAILABLE"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "services/developerPayoutDestinationService.js",
          "services/developerPayoutEmailVerificationService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "provider": {
                    "type": "string",
                    "enum": [
                      "stripe",
                      "paypal"
                    ]
                  },
                  "environment": {
                    "type": "string",
                    "enum": [
                      "test",
                      "live"
                    ]
                  },
                  "paypalEmail": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 127,
                    "pattern": "^[\\x21-\\x7e]+$"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 127,
                    "pattern": "^[\\x21-\\x7e]+$",
                    "description": "Supported alias for paypalEmail."
                  },
                  "paypalAccountCountry": {
                    "type": "string"
                  },
                  "confirmPayPalAccount": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "provider"
                ],
                "allOf": [
                  {
                    "if": {
                      "properties": {
                        "provider": {
                          "const": "paypal"
                        }
                      },
                      "required": [
                        "provider"
                      ]
                    },
                    "then": {
                      "properties": {
                        "confirmPayPalAccount": {
                          "const": true
                        }
                      },
                      "required": [
                        "confirmPayPalAccount"
                      ]
                    }
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/payouts/payout-readiness": {
      "get": {
        "summary": "GET /api/developer/settlements/payout-readiness",
        "description": "Active compatibility alias of GET /api/developer/settlements/payout-readiness. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. Can initialize a local settlement account, recalculate balances and refresh a configured Stripe Connect account. Not a zero-write uptime probe. payout_ready is an account/destination status, not approval to send, a guaranteed net amount or confirmed bank receipt. No transfer or automatic-execution setting is changed.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/billing"
        },
        "parameters": [
          {
            "name": "currency",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "usd"
            }
          },
          {
            "name": "environment",
            "in": "query",
            "schema": {
              "enum": [
                "live",
                "test"
              ],
              "default": "live"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "billing.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/developerSettlementRoutes.js",
          "services/payoutSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/payouts/payout-status/refresh": {
      "post": {
        "summary": "POST /api/developer/settlements/payout-status/refresh",
        "description": "Active compatibility alias of POST /api/developer/settlements/payout-status/refresh. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "x-access-scope": "billing.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-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/payouts/payouts/bank-payouts": {
      "get": {
        "summary": "GET /api/developer/settlements/bank-payouts",
        "description": "Active compatibility alias of GET /api/developer/settlements/bank-payouts. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/connectPayoutService.js"
        ]
      }
    },
    "/api/developer/payouts/payouts/history": {
      "get": {
        "summary": "GET /api/developer/settlements/history",
        "description": "Active compatibility alias of GET /api/developer/settlements/history. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. Transfer payout_fee records distinguish the original deduction, actual provider fee, prior adjustment, estimated cross-border component and FX quote/settlement. Pending or unclaimed payment is not bank receipt; unreserved fee adjustments can change a later payout.",
        "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": "See the linked operation reference for the response contract.",
            "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
                                },
                                "provider": {
                                  "type": "string"
                                },
                                "payout_fee": {
                                  "anyOf": [
                                    {
                                      "type": "object",
                                      "properties": {
                                        "feeCents": {
                                          "type": "integer",
                                          "minimum": 0
                                        },
                                        "actualFeeCents": {
                                          "anyOf": [
                                            {
                                              "type": "integer",
                                              "minimum": 0
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        },
                                        "adjustmentCents": {
                                          "type": "integer"
                                        },
                                        "differenceCents": {
                                          "anyOf": [
                                            {
                                              "type": "integer"
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        },
                                        "status": {
                                          "type": "string"
                                        },
                                        "feeComponents": {
                                          "type": "array",
                                          "items": {
                                            "type": "object",
                                            "properties": {
                                              "id": {
                                                "type": "string"
                                              },
                                              "kind": {
                                                "type": "string"
                                              },
                                              "basis": {
                                                "type": "string"
                                              },
                                              "amountCents": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "additionalProperties": true
                                          }
                                        },
                                        "crossBorderEstimated": {
                                          "type": "boolean"
                                        },
                                        "crossBorderFeeCents": {
                                          "type": "integer",
                                          "minimum": 0
                                        },
                                        "crossBorderEstimateBasisPoints": {
                                          "anyOf": [
                                            {
                                              "type": "integer",
                                              "minimum": 0
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        },
                                        "fx": {
                                          "anyOf": [
                                            {
                                              "type": "object",
                                              "properties": {
                                                "currency": {
                                                  "type": "string"
                                                },
                                                "localNetMinor": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "actualLocalNetMinor": {
                                                  "anyOf": [
                                                    {
                                                      "type": "integer",
                                                      "minimum": 0
                                                    },
                                                    {
                                                      "type": "null"
                                                    }
                                                  ]
                                                },
                                                "conversionFeeCents": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "actualExchangeRate": {
                                                  "type": "string"
                                                },
                                                "quote": {
                                                  "type": "object",
                                                  "properties": {
                                                    "id": {
                                                      "type": "string"
                                                    },
                                                    "exchangeRate": {
                                                      "type": "string"
                                                    },
                                                    "expiresAt": {
                                                      "type": "string",
                                                      "format": "date-time"
                                                    }
                                                  },
                                                  "additionalProperties": true
                                                },
                                                "settlementVerified": {
                                                  "type": "boolean"
                                                }
                                              },
                                              "additionalProperties": true
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        }
                                      },
                                      "additionalProperties": true
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "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
                      }
                    },
                    "pendingFeeAdjustmentCents": {
                      "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/payoutHistoryReportingService.js",
          "services/revenueReportingScope.js",
          "services/developerPayoutFeeDisclosure.js"
        ]
      }
    },
    "/api/developer/payouts/payouts/history/export.csv": {
      "get": {
        "summary": "GET /api/developer/settlements/history/export.csv",
        "description": "Active compatibility alias of GET /api/developer/settlements/history/export.csv. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. The 28 columns, in order, are: Batch, Currency, First sale UTC, Last sale UTC, Scheduled run, Batch earnings cents, Batch status, Invoice offset cents, Transfer reference, Net payout cents, Transfer status, Bank reference, Bank status, Original payout fee deduction cents, Actual payout fee cents, Prior fee adjustment cents, Fee status, Cross-border fee estimated, Cross-border estimate cents included, Cross-border estimate basis points, Quoted FX cost USD cents, Recorded exchange rate, Local payout currency, Recorded local net minor units, FX quote expiry UTC, Conversion status, Fee difference cents, Reconciliation status. Net payout cents is the recorded transfer amount, not gross sale proceeds or guaranteed bank receipt. Actual fee and reconciliation fields can be unavailable until the provider record exists; an empty value is not a confirmed zero. Quoted FX cost is already included in its quoted conversion, not an instruction to subtract it twice. Cross-border estimate cents included is already part of the original deduction. Current accounting is USD; Recorded local net minor units instead uses Local payout currency. Conversion status is confirmed only for a verified settlement, expired_quote for an expired or imminent-expiry quote, unavailable for missing/invalid quote expiry, and quoted for a quote outside that expiry boundary. No FX record leaves this column empty. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/payoutHistoryReportingService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/payouts/payouts/summary": {
      "get": {
        "summary": "GET /api/developer/settlements/summary",
        "description": "Active compatibility alias of GET /api/developer/settlements/summary. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. The summary selects the upcoming payout run, not the oldest unpaid run used by owner payment preparation. available_cents belongs to that selected sales period; held_cents can include unpaid earnings outside it or on hold. owed_cents covers the scoped unpaid balance across periods and is not the forecast net or permission to send. unresolved_source_entries/cents identify historical entries without complete order/environment evidence, excluded from confirmed payable totals. payoutForecast is an estimate for the selected Eastern period, not payout eligibility or permission to send: readyToSend is always false. It keeps known sales/usage visible while processingKnown:false leaves processingCents, totalNonSaleCents and netBeforePayoutFeesCents null. A negative net produces amountDueCents rather than a negative transfer. payoutFeePreview can have basis:period_forecast and forecastOnly:true; it is not a completed payment. 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. payoutFeePreview is a read-only projection or prepared amount, not payment execution. The next-run estimate can include recorded earnings that mature by that run. USD accounting, local payout currency, quoted FX cost, estimated provider fees and bank receipt are separate facts. feeComponents preserve each provider component basis and USD-cent amount; actualFeeCents and signed differenceCents are supplied when reconciliation records are available.",
        "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": "See the linked operation reference for the response contract.",
            "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."
                        },
                        "owed_cents": {
                          "type": [
                            "integer",
                            "string"
                          ],
                          "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                        },
                        "source_model": {
                          "type": "string",
                          "enum": [
                            "journal",
                            "legacy"
                          ]
                        },
                        "unresolved_source_entries": {
                          "type": "integer"
                        },
                        "unresolved_source_cents": {
                          "type": [
                            "integer",
                            "string"
                          ],
                          "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                        },
                        "accounting_adjustment_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",
                          "description": "Nominal wait in days. Fixed half-month windows govern eligibility, including short February; this is not an exact rolling hold."
                        },
                        "payout_window_policy": {
                          "type": "string"
                        },
                        "hold_is_approximate": {
                          "type": "boolean"
                        },
                        "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."
                    },
                    "payoutForecast": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "const": "payout-period-forecast-v1"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "available": {
                          "type": "boolean"
                        },
                        "processingKnown": {
                          "type": "boolean"
                        },
                        "pendingProcessingCount": {
                          "type": "integer"
                        },
                        "salesCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "salesFeeCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "earningsBeforeUsageCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "marketingEmailCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "redemptionCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "minimumCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "serviceCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "knownProcessingCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "processingCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "totalNonSaleCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "netBeforePayoutFeesCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "totalDeductionsBeforePayoutFeeCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "amountDueCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "minimumBasis": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "readyToSend": {
                          "const": false
                        },
                        "period_start": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "period_end": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "runDate": {
                          "type": "string",
                          "format": "date"
                        },
                        "charges": {
                          "type": "object",
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "period_start": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "period_end": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "marketing_email_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "redemption_overage_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_adjustment_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "developer_service_fee_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "provider_processing_fees_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "non_sale_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_qualifying_basis": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        },
                        "feePreview": {
                          "type": "object",
                          "properties": {
                            "basis": {
                              "const": "period_forecast"
                            },
                            "projected": {
                              "type": "boolean"
                            },
                            "forecastOnly": {
                              "type": "boolean"
                            },
                            "status": {
                              "type": "string"
                            },
                            "grossCents": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "netCents": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "feeCents": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "currency": {
                              "type": "string"
                            },
                            "provider": {
                              "type": "string"
                            },
                            "country": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "businessCountry": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "payoutCurrency": {
                              "type": "string"
                            },
                            "message": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    },
                    "payoutFeePreview": {
                      "type": "object",
                      "properties": {
                        "enabled": {
                          "type": "boolean"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "waiting",
                            "setup_required",
                            "unavailable",
                            "prepared",
                            "calculated",
                            "estimated"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "currency": {
                          "const": "usd"
                        },
                        "provider": {
                          "type": "string",
                          "enum": [
                            "stripe",
                            "paypal"
                          ]
                        },
                        "country": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "businessCountry": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "payoutCurrency": {
                          "type": "string"
                        },
                        "estimated": {
                          "type": "boolean"
                        },
                        "projected": {
                          "type": "boolean"
                        },
                        "basis": {
                          "type": "string"
                        },
                        "runDate": {
                          "type": "string"
                        },
                        "eligibleAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "transferIntentId": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 1
                            },
                            {
                              "type": "string",
                              "pattern": "^[1-9][0-9]*$"
                            }
                          ]
                        },
                        "grossCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "billingOffsetCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "adjustmentCents": {
                          "type": "integer"
                        },
                        "roundingCarryCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "feeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "netCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "transferFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "crossBorderFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "settlementFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "feeComponents": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "kind": {
                                "type": "string"
                              },
                              "basis": {
                                "type": "string"
                              },
                              "amountCents": {
                                "type": "integer",
                                "minimum": 0
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "conversionFeeCents": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "recipientConversionIncluded": {
                          "type": "boolean"
                        },
                        "monthlyFeePeriod": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "localNetMinor": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "exchangeRate": {
                          "type": "string"
                        },
                        "totalDeveloperFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "netUsdEquivalentCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "fxFeeTreatment": {
                          "type": "string"
                        },
                        "fxQuoteExpiresAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "fxSettled": {
                          "type": "boolean"
                        },
                        "crossBorderEstimated": {
                          "type": "boolean"
                        },
                        "crossBorderEstimateBasisPoints": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "actualFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "differenceCents": {
                          "type": "integer"
                        },
                        "feeReconciled": {
                          "type": "boolean"
                        },
                        "reconciliationStatus": {
                          "type": "string"
                        },
                        "feeDisclosure": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "calculation": {
                          "type": "string"
                        },
                        "period_start": {
                          "type": "string"
                        },
                        "period_end": {
                          "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/transferIntentService.js",
          "services/externalPartnerSalesReportingService.js",
          "services/payoutPeriodForecastService.js",
          "services/actualProcessingFeeService.js",
          "services/developerPayoutPreviewService.js",
          "services/developerStripeLocalPayoutService.js",
          "services/developerPayoutUpfrontRates.js",
          "services/developerPayoutFeeDisclosure.js"
        ]
      }
    },
    "/api/developer/payouts/payouts/transfers": {
      "get": {
        "summary": "GET /api/developer/settlements/transfers",
        "description": "Active compatibility alias of GET /api/developer/settlements/transfers. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/transferIntentService.js"
        ]
      }
    },
    "/api/developer/payouts/payouts/transfers/{id}": {
      "get": {
        "summary": "GET /api/developer/settlements/transfers/{id}",
        "description": "Active compatibility alias of GET /api/developer/settlements/transfers/{id}. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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/payouts/recovery/cases": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/cases",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/cases. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "MOR_RECOVERY_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/payouts/recovery/cases/{id}": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/cases/{id}",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/cases/{id}. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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/payouts/recovery/offsets": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/offsets",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/offsets. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/payouts/recovery/reserve": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/reserve",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/reserve. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "MOR_RECOVERY_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/payouts/recovery/statements": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/statements",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/statements. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/payouts/recovery/summary": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/summary",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/summary. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/payouts/settlements-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/settlements-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/settlements-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "INVALID_ALLOCATION_STATE",
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/payouts/statements-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/statements-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/statements-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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 Eastern calendar 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": "See the linked operation reference for the response contract.",
            "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",
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "period_start": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "period_end": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "marketing_email_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "redemption_overage_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_adjustment_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "developer_service_fee_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "provider_processing_fees_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "non_sale_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_qualifying_basis": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "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": "AccountSession",
        "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": [
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/payouts/summary": {
      "get": {
        "summary": "GET /api/developer/settlements/summary",
        "description": "Active compatibility alias of GET /api/developer/settlements/summary. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. The summary selects the upcoming payout run, not the oldest unpaid run used by owner payment preparation. available_cents belongs to that selected sales period; held_cents can include unpaid earnings outside it or on hold. owed_cents covers the scoped unpaid balance across periods and is not the forecast net or permission to send. unresolved_source_entries/cents identify historical entries without complete order/environment evidence, excluded from confirmed payable totals. payoutForecast is an estimate for the selected Eastern period, not payout eligibility or permission to send: readyToSend is always false. It keeps known sales/usage visible while processingKnown:false leaves processingCents, totalNonSaleCents and netBeforePayoutFeesCents null. A negative net produces amountDueCents rather than a negative transfer. payoutFeePreview can have basis:period_forecast and forecastOnly:true; it is not a completed payment. 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. payoutFeePreview is a read-only projection or prepared amount, not payment execution. The next-run estimate can include recorded earnings that mature by that run. USD accounting, local payout currency, quoted FX cost, estimated provider fees and bank receipt are separate facts. feeComponents preserve each provider component basis and USD-cent amount; actualFeeCents and signed differenceCents are supplied when reconciliation records are available.",
        "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": "See the linked operation reference for the response contract.",
            "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."
                        },
                        "owed_cents": {
                          "type": [
                            "integer",
                            "string"
                          ],
                          "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                        },
                        "source_model": {
                          "type": "string",
                          "enum": [
                            "journal",
                            "legacy"
                          ]
                        },
                        "unresolved_source_entries": {
                          "type": "integer"
                        },
                        "unresolved_source_cents": {
                          "type": [
                            "integer",
                            "string"
                          ],
                          "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                        },
                        "accounting_adjustment_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",
                          "description": "Nominal wait in days. Fixed half-month windows govern eligibility, including short February; this is not an exact rolling hold."
                        },
                        "payout_window_policy": {
                          "type": "string"
                        },
                        "hold_is_approximate": {
                          "type": "boolean"
                        },
                        "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."
                    },
                    "payoutForecast": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "const": "payout-period-forecast-v1"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "available": {
                          "type": "boolean"
                        },
                        "processingKnown": {
                          "type": "boolean"
                        },
                        "pendingProcessingCount": {
                          "type": "integer"
                        },
                        "salesCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "salesFeeCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "earningsBeforeUsageCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "marketingEmailCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "redemptionCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "minimumCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "serviceCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "knownProcessingCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "processingCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "totalNonSaleCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "netBeforePayoutFeesCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "totalDeductionsBeforePayoutFeeCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "amountDueCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "minimumBasis": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "readyToSend": {
                          "const": false
                        },
                        "period_start": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "period_end": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "runDate": {
                          "type": "string",
                          "format": "date"
                        },
                        "charges": {
                          "type": "object",
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "period_start": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "period_end": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "marketing_email_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "redemption_overage_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_adjustment_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "developer_service_fee_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "provider_processing_fees_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "non_sale_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_qualifying_basis": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        },
                        "feePreview": {
                          "type": "object",
                          "properties": {
                            "basis": {
                              "const": "period_forecast"
                            },
                            "projected": {
                              "type": "boolean"
                            },
                            "forecastOnly": {
                              "type": "boolean"
                            },
                            "status": {
                              "type": "string"
                            },
                            "grossCents": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "netCents": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "feeCents": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "currency": {
                              "type": "string"
                            },
                            "provider": {
                              "type": "string"
                            },
                            "country": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "businessCountry": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "payoutCurrency": {
                              "type": "string"
                            },
                            "message": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    },
                    "payoutFeePreview": {
                      "type": "object",
                      "properties": {
                        "enabled": {
                          "type": "boolean"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "waiting",
                            "setup_required",
                            "unavailable",
                            "prepared",
                            "calculated",
                            "estimated"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "currency": {
                          "const": "usd"
                        },
                        "provider": {
                          "type": "string",
                          "enum": [
                            "stripe",
                            "paypal"
                          ]
                        },
                        "country": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "businessCountry": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "payoutCurrency": {
                          "type": "string"
                        },
                        "estimated": {
                          "type": "boolean"
                        },
                        "projected": {
                          "type": "boolean"
                        },
                        "basis": {
                          "type": "string"
                        },
                        "runDate": {
                          "type": "string"
                        },
                        "eligibleAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "transferIntentId": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 1
                            },
                            {
                              "type": "string",
                              "pattern": "^[1-9][0-9]*$"
                            }
                          ]
                        },
                        "grossCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "billingOffsetCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "adjustmentCents": {
                          "type": "integer"
                        },
                        "roundingCarryCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "feeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "netCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "transferFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "crossBorderFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "settlementFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "feeComponents": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "kind": {
                                "type": "string"
                              },
                              "basis": {
                                "type": "string"
                              },
                              "amountCents": {
                                "type": "integer",
                                "minimum": 0
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "conversionFeeCents": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "recipientConversionIncluded": {
                          "type": "boolean"
                        },
                        "monthlyFeePeriod": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "localNetMinor": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "exchangeRate": {
                          "type": "string"
                        },
                        "totalDeveloperFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "netUsdEquivalentCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "fxFeeTreatment": {
                          "type": "string"
                        },
                        "fxQuoteExpiresAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "fxSettled": {
                          "type": "boolean"
                        },
                        "crossBorderEstimated": {
                          "type": "boolean"
                        },
                        "crossBorderEstimateBasisPoints": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "actualFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "differenceCents": {
                          "type": "integer"
                        },
                        "feeReconciled": {
                          "type": "boolean"
                        },
                        "reconciliationStatus": {
                          "type": "string"
                        },
                        "feeDisclosure": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "calculation": {
                          "type": "string"
                        },
                        "period_start": {
                          "type": "string"
                        },
                        "period_end": {
                          "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/transferIntentService.js",
          "services/externalPartnerSalesReportingService.js",
          "services/payoutPeriodForecastService.js",
          "services/actualProcessingFeeService.js",
          "services/developerPayoutPreviewService.js",
          "services/developerStripeLocalPayoutService.js",
          "services/developerPayoutUpfrontRates.js",
          "services/developerPayoutFeeDisclosure.js"
        ]
      }
    },
    "/api/developer/payouts/summary-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/summary-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/summary-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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 Eastern calendar 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": "See the linked operation reference for the response contract.",
            "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",
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "period_start": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "period_end": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "marketing_email_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "redemption_overage_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_adjustment_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "developer_service_fee_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "provider_processing_fees_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "non_sale_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_qualifying_basis": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "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": "AccountSession",
        "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": [
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/payouts/transactions-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/transactions-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/transactions-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "INVALID_ALLOCATION_STATE",
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/payouts/transfers": {
      "get": {
        "summary": "GET /api/developer/settlements/transfers",
        "description": "Active compatibility alias of GET /api/developer/settlements/transfers. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/transferIntentService.js"
        ]
      }
    },
    "/api/developer/payouts/transfers/{id}": {
      "get": {
        "summary": "GET /api/developer/settlements/transfers/{id}",
        "description": "Active compatibility alias of GET /api/developer/settlements/transfers/{id}. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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/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 session token",
        "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": {
      "get": {
        "summary": "List legacy keys owned by the signed-in actor",
        "description": "Historical developer-level keys are selected by the signed-in actor user ID, not the selected workspace developer ID. A workspace selector cannot reveal or delete another actor's keys. Prefer product-scoped credentials for maintained integrations.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/product-credentials"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: ok, keys.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "keys": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": [
                              "integer",
                              "string"
                            ]
                          },
                          "label": {
                            "type": "string"
                          },
                          "appId": {
                            "type": "string"
                          },
                          "isActive": {
                            "type": "boolean"
                          },
                          "createdAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "lastUsedAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          }
                        },
                        "additionalProperties": true
                      }
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "ok",
                    "keys"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/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 session token",
        "x-access-scope": "api_keys.view and all-products scope; only the signed-in actor's legacy key rows.",
        "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/devKeysRoutes.js",
          "controllers/devPluginKeysController.js"
        ]
      },
      "post": {
        "summary": "Read the retired developer-level key-creation response",
        "description": "Returns 410 LEGACY_KEY_CREATION_DISABLED after authentication and permission checks; no key is created or secret returned. Create a product-scoped credential instead.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/product-credentials"
        },
        "parameters": [],
        "responses": {
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "410": {
            "description": "HTTP 410: ok, code, error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "code": {
                      "const": "LEGACY_KEY_CREATION_DISABLED"
                    },
                    "error": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "ok",
                    "code",
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "api_keys.manage and all-products scope; the handler then returns the retired compatibility response.",
        "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/devKeysRoutes.js",
          "controllers/devPluginKeysController.js"
        ],
        "deprecated": true
      }
    },
    "/api/developer/plugin-keys/{id}": {
      "delete": {
        "summary": "Delete a legacy key owned by the signed-in actor",
        "description": "Historical developer-level keys are selected by the signed-in actor user ID, not the selected workspace developer ID. A workspace selector cannot reveal or delete another actor's keys. Prefer product-scoped credentials for maintained integrations. Deletes that legacy credential row. This is destructive cleanup, not product-key rotation or a harmless read; confirm that distributed clients no longer depend on it. Unknown/foreign rows return 404 Key not found. No replacement secret or package is generated.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/product-credentials"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: ok.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/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 session token",
        "x-access-scope": "api_keys.manage and all-products scope; DELETE also requires the legacy row to belong to the signed-in actor.",
        "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/devKeysRoutes.js",
          "controllers/devPluginKeysController.js"
        ]
      }
    },
    "/api/developer/plugin-keys/{id}/secret": {
      "get": {
        "summary": "Read the retired legacy secret-reveal response",
        "description": "Returns 410 LEGACY_SECRET_REVEAL_DISABLED after authentication and permission checks; no key is created or secret returned. Existing legacy secrets cannot be revealed. Use the current product credential lifecycle and coordinate deliberate rotation if needed.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/product-credentials"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "410": {
            "description": "HTTP 410: ok, code, error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "code": {
                      "const": "LEGACY_SECRET_REVEAL_DISABLED"
                    },
                    "error": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "ok",
                    "code",
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "api_keys.view and all-products scope; the handler then returns the retired compatibility response.",
        "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/devKeysRoutes.js",
          "controllers/devPluginKeysController.js"
        ],
        "deprecated": true
      }
    },
    "/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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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/practice/juce-demo": {
      "get": {
        "summary": "GET /api/developer/practice/juce-demo",
        "description": "Uses ordinary JUCE activation, email verification, validation and deactivation. Verification is captured in the owner Practice inbox. Temporary serials last seven days. No production data or financial operation is created. Reset revokes the previous serial and online activations; offline devices follow their already signed grace deadline.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/evaluation"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: demo.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "demo": {
                      "oneOf": [
                        {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "productId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "appId": {
                              "type": "string"
                            },
                            "apiBaseUrl": {
                              "type": "string",
                              "format": "uri"
                            },
                            "serial": {
                              "type": "string"
                            },
                            "expiresAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "expired": {
                              "type": "boolean"
                            },
                            "temporary": {
                              "const": true
                            },
                            "outsideCatalog": {
                              "const": true
                            },
                            "packagePath": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "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"
                }
              }
            }
          },
          "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 session token",
        "x-access-scope": "Isolated evaluation only; developer account owner with storefront.view and all-product scope. No product or service selection required. Demo is outside the developer catalog.",
        "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/developerPracticeRoutes.js",
          "services/practiceJuceDemoService.js"
        ]
      },
      "post": {
        "summary": "POST /api/developer/practice/juce-demo",
        "description": "Uses ordinary JUCE activation, email verification, validation and deactivation. Verification is captured in the owner Practice inbox. Temporary serials last seven days. No production data or financial operation is created. Reset revokes the previous serial and online activations; offline devices follow their already signed grace deadline.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/evaluation"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: demo.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "demo": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "appId": {
                          "type": "string"
                        },
                        "apiBaseUrl": {
                          "type": "string",
                          "format": "uri"
                        },
                        "serial": {
                          "type": "string"
                        },
                        "expiresAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "expired": {
                          "type": "boolean"
                        },
                        "temporary": {
                          "const": true
                        },
                        "outsideCatalog": {
                          "const": true
                        },
                        "packagePath": {
                          "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"
                }
              }
            }
          },
          "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 session token",
        "x-access-scope": "Isolated evaluation only; developer account owner with storefront.view and all-product scope. No product or service selection required. Demo is outside the developer catalog.",
        "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/developerPracticeRoutes.js",
          "services/practiceJuceDemoService.js"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/developer/practice/juce-demo/package": {
      "post": {
        "summary": "POST /api/developer/practice/juce-demo/package",
        "description": "Uses ordinary JUCE activation, email verification, validation and deactivation. Verification is captured in the owner Practice inbox. Temporary serials last seven days. No production data or financial operation is created. Reset revokes the previous serial and online activations; offline devices follow their already signed grace deadline. Returns a five-minute private package download, not ZIP bytes or a server secret. Includes normal JUCE source, configured public IDs/verification keys and demo instructions. Hosted Practice requires HTTPS; local packages permit only the exact configured loopback origin.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/evaluation"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: url, filename, expiresIn.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "filename": {
                      "type": "string"
                    },
                    "expiresIn": {
                      "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"
                }
              }
            }
          },
          "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 session token",
        "x-access-scope": "Isolated evaluation only; developer account owner with storefront.view and all-product scope. No product or service selection required. Demo is outside the developer catalog.",
        "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/developerPracticeRoutes.js",
          "services/practiceJuceDemoService.js"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/developer/practice/juce-demo/reset": {
      "post": {
        "summary": "POST /api/developer/practice/juce-demo/reset",
        "description": "Uses ordinary JUCE activation, email verification, validation and deactivation. Verification is captured in the owner Practice inbox. Temporary serials last seven days. No production data or financial operation is created. Reset revokes the previous serial and online activations; offline devices follow their already signed grace deadline.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/evaluation"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: demo.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "demo": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "appId": {
                          "type": "string"
                        },
                        "apiBaseUrl": {
                          "type": "string",
                          "format": "uri"
                        },
                        "serial": {
                          "type": "string"
                        },
                        "expiresAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "expired": {
                          "type": "boolean"
                        },
                        "temporary": {
                          "const": true
                        },
                        "outsideCatalog": {
                          "const": true
                        },
                        "packagePath": {
                          "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"
                }
              }
            }
          },
          "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 session token",
        "x-access-scope": "Isolated evaluation only; developer account owner with storefront.view and all-product scope. No product or service selection required. Demo is outside the developer catalog.",
        "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/developerPracticeRoutes.js",
          "services/practiceJuceDemoService.js"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "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. Expansion reads require products.view and changes require products.edit. Parent and child products must belong to the active workspace and be assigned to a product-scoped teammate. Relationship lists filter unassigned products. The acting teammate is not the workspace product owner.",
        "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 session token",
        "x-access-scope": "products.view for reads; products.edit for changes. Both parent and child must belong to the effective workspace and be assigned to a selected-product teammate. Relationship lists exclude unassigned products.",
        "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",
          "services/developerRbacScopeService.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. Expansion reads require products.view and changes require products.edit. Parent and child products must belong to the active workspace and be assigned to a product-scoped teammate. Relationship lists filter unassigned products. The acting teammate is not the workspace product owner.",
        "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 session token",
        "x-access-scope": "products.view for reads; products.edit for changes. Both parent and child must belong to the effective workspace and be assigned to a selected-product teammate. Relationship lists exclude unassigned 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/developerExpansionRoutes.js",
          "services/expansionFoundationService.js",
          "services/developerRbacScopeService.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 session token",
        "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 session token",
        "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. Expansion reads require products.view and changes require products.edit. Parent and child products must belong to the active workspace and be assigned to a product-scoped teammate. Relationship lists filter unassigned products. The acting teammate is not the workspace product owner.",
        "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 session token",
        "x-access-scope": "products.view for reads; products.edit for changes. Both parent and child must belong to the effective workspace and be assigned to a selected-product teammate. Relationship lists exclude unassigned products.",
        "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",
          "services/developerRbacScopeService.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. Expansion reads require products.view and changes require products.edit. Parent and child products must belong to the active workspace and be assigned to a product-scoped teammate. Relationship lists filter unassigned products. The acting teammate is not the workspace product owner.",
        "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 session token",
        "x-access-scope": "products.view for reads; products.edit for changes. Both parent and child must belong to the effective workspace and be assigned to a selected-product teammate. Relationship lists exclude unassigned products.",
        "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",
          "services/developerRbacScopeService.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": "Expansion reads require products.view and changes require products.edit. Parent and child products must belong to the active workspace and be assigned to a product-scoped teammate. Relationship lists filter unassigned products. The acting teammate is not the workspace product owner.",
        "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 session token",
        "x-access-scope": "products.view for reads; products.edit for changes. Both parent and child must belong to the effective workspace and be assigned to a selected-product teammate. Relationship lists exclude unassigned 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/developerExpansionRoutes.js",
          "services/expansionFoundationService.js",
          "services/developerRbacScopeService.js"
        ]
      },
      "post": {
        "summary": "Link an existing expansion to this parent",
        "description": "Expansion reads require products.view and changes require products.edit. Parent and child products must belong to the active workspace and be assigned to a product-scoped teammate. Relationship lists filter unassigned products. The acting teammate is not the workspace product owner.",
        "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 session token",
        "x-access-scope": "products.view for reads; products.edit for changes. Both parent and child must belong to the effective workspace and be assigned to a selected-product teammate. Relationship lists exclude unassigned products.",
        "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",
          "services/developerRbacScopeService.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 session token",
        "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. New private-file attachments require a verified object authorized for the effective workspace and source-product assignment. Knowing another workspace storage key is not authorization. Deduplicated objects require this workspace's verified upload proof or an existing permitted product reference. New-policy file arrays cannot bypass the managed attachment workflow. Existing historical references are retained; new legacy attachments and version-file references still require ownership proof.",
        "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 session token",
        "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-error-codes": [
          "PRODUCT_FILE_NOT_ACCESSIBLE",
          "PRODUCT_FILE_NOT_VERIFIED",
          "MANAGED_FILE_ATTACHMENT_REQUIRED"
        ],
        "x-source-files": [
          "routes/developerPlatformToolsRoutes.js",
          "services/betaPlatformToolsService.js",
          "services/productFileOwnershipService.js",
          "services/developerServiceOptionService.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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 final paid-cart minimum after discounts and before tax; individual qualifying discounted lines can be lower. Subscription payments retain their supported minimum checks.",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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. Workspace readiness requires products.view and all-products scope; storefront readiness requires storefront.view and all-products scope. Product readiness requires products.view, assignment and active-workspace ownership. Workspace billing, settlement, email and partner categories follow their existing view permissions and are not queried for unauthorized roles.",
        "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 session token",
        "x-access-scope": "products.view, assigned-product scope and active-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/developerReadinessRoutes.js",
          "services/developerReadinessService.js",
          "services/developerReadinessSummaryService.js",
          "services/developerRbacScopeService.js"
        ]
      }
    },
    "/api/developer/products/{productId}/relationships": {
      "get": {
        "summary": "Read active or inactive product relationships",
        "description": "Expansion reads require products.view and changes require products.edit. Parent and child products must belong to the active workspace and be assigned to a product-scoped teammate. Relationship lists filter unassigned products. The acting teammate is not the workspace product owner.",
        "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 session token",
        "x-access-scope": "products.view for reads; products.edit for changes. Both parent and child must belong to the effective workspace and be assigned to a selected-product teammate. Relationship lists exclude unassigned products.",
        "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",
          "services/developerRbacScopeService.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 session token",
        "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 session token",
        "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 session token",
        "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": "Expansion reads require products.view and changes require products.edit. Parent and child products must belong to the active workspace and be assigned to a product-scoped teammate. Relationship lists filter unassigned products. The acting teammate is not the workspace product owner.",
        "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 session token",
        "x-access-scope": "products.view for reads; products.edit for changes. Both parent and child must belong to the effective workspace and be assigned to a selected-product teammate. Relationship lists exclude unassigned 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/developerExpansionRoutes.js",
          "services/expansionFoundationService.js",
          "services/developerRbacScopeService.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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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"
                            },
                            "costCents": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "costBasis": {
                              "const": "current_policy_estimate"
                            },
                            "emailsSentCount": {
                              "type": "integer"
                            },
                            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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
                              }
                            },
                            "productMatch": {
                              "type": "string",
                              "enum": [
                                "any",
                                "all"
                              ]
                            },
                            "excludeCampaignIds": {
                              "type": "array",
                              "maxItems": 50,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                            },
                            "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 session token",
        "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
                        }
                      },
                      "productMatch": {
                        "type": "string",
                        "enum": [
                          "any",
                          "all"
                        ]
                      },
                      "excludeCampaignIds": {
                        "type": "array",
                        "maxItems": 50,
                        "items": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
                      },
                      "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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}": {
      "delete": {
        "summary": "Soft-delete an authorized code or offer",
        "description": "Soft-deletes an authorized code or offer after pausing/archiving it. Existing receipts and historical records remain. Deleting a reward program stops new grants but does not revoke its already issued coupons; deleting an individual code disables future redemption. Workspace/product permissions still apply. This is not a refund or a data-erasure request.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/promotions"
        },
        "parameters": [
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: deleted, kind, id.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "code",
                        "offer"
                      ]
                    },
                    "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"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "Existing marketing.manage and workspace/product scope 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": [
          "routes/developerPromotionRoutes.js",
          "services/developerPromotionService.js",
          "services/promotionWorkspaceService.js",
          "services/promotionWorkspaceService.js"
        ]
      },
      "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 session token",
        "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": "Supported discount type/value changes are saved without changing the code identity or historical receipt snapshots. Code identity, product scope and other immutable offer-family fields still follow their existing rules; duplicate the promotion for a different immutable configuration. Archived records must be restored before editing; deleted records are unavailable.",
        "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 session token",
        "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 session token",
        "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 session token",
        "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-<entitlement ID>; 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. For external reseller estimates, feeBps is 0: no SoundSync checkout percentage applies. Provider costs and applicable service/redemption charges are separate, not estimated here. recordedAllocation preserves an original unfunded allocation; recordedAdjustmentCents reconciles its net against the currently resolved price/split and recorded collaborator amount, not a new fee or payment. Managed-sale developer allocation fields are before separately billed account charges, not a final payout. receipt_promotions contains deduplicated saved promotion names and codes from accepted order/item/provider snapshots, not the campaign current name. item_promotions retains multiple saved purchase-option deal snapshots; coupon_code and item_sale_name remain compatibility fields. Non-financial access rows return no receipt promotions. This private response is no-store; do not treat displayed discounts as current offer availability.",
        "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": "all, 1d, 1w, 2w, 1m or custom. Legacy YYYY-MM-DD_to_YYYY-MM-DD is supported. Non-custom presets clear stale calendar dates."
          },
          {
            "name": "dateFrom",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": false,
            "description": "Inclusive UTC calendar start, not the Eastern accounting month."
          },
          {
            "name": "dateTo",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": false,
            "description": "Inclusive UTC calendar end; the SQL upper bound is the next midnight."
          },
          {
            "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": ""
          }
        ],
        "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"
                          },
                          "reseller_estimate": {
                            "type": "object",
                            "properties": {
                              "feeBps": {
                                "const": 0
                              },
                              "saleCents": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "rate": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "resellerCents": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "feeCents": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "payoutCents": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "partnerShareCents": {
                                "type": "integer"
                              },
                              "recordedAllocation": {
                                "type": "boolean"
                              },
                              "recordedAdjustmentCents": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "refunded": {
                                "type": "boolean"
                              },
                              "currentTerms": {
                                "type": "boolean"
                              },
                              "unavailableReason": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            },
                            "additionalProperties": true
                          },
                          "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"
                                },
                                "reseller_estimate": {
                                  "type": "object",
                                  "properties": {
                                    "feeBps": {
                                      "const": 0
                                    },
                                    "saleCents": {
                                      "type": [
                                        "integer",
                                        "null"
                                      ]
                                    },
                                    "rate": {
                                      "type": [
                                        "number",
                                        "null"
                                      ]
                                    },
                                    "resellerCents": {
                                      "type": [
                                        "integer",
                                        "null"
                                      ]
                                    },
                                    "feeCents": {
                                      "type": [
                                        "integer",
                                        "null"
                                      ]
                                    },
                                    "payoutCents": {
                                      "type": [
                                        "integer",
                                        "null"
                                      ]
                                    },
                                    "partnerShareCents": {
                                      "type": "integer"
                                    },
                                    "recordedAllocation": {
                                      "type": "boolean"
                                    },
                                    "recordedAdjustmentCents": {
                                      "type": [
                                        "integer",
                                        "null"
                                      ]
                                    },
                                    "refunded": {
                                      "type": "boolean"
                                    },
                                    "currentTerms": {
                                      "type": "boolean"
                                    },
                                    "unavailableReason": {
                                      "type": [
                                        "string",
                                        "null"
                                      ]
                                    }
                                  },
                                  "additionalProperties": true
                                },
                                "metadata": {
                                  "type": "object",
                                  "additionalProperties": true,
                                  "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "coupon_code": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "item_promotion": {
                            "type": "object",
                            "properties": {
                              "title": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "couponCode": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              }
                            },
                            "additionalProperties": true
                          },
                          "item_promotions": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "title": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "couponCode": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "item_sale_name": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "receipt_promotions": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "code": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "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 session token",
        "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. all, 1d, 1w, 2w, 1m or custom. Legacy YYYY-MM-DD_to_YYYY-MM-DD is supported. Non-custom presets clear stale calendar dates.",
          "query dateFrom: string. Inclusive UTC calendar start, not the Eastern accounting month.",
          "query dateTo: string. Inclusive UTC calendar end; the SQL upper bound is the next midnight.",
          "query productId: integer",
          "query channel: value",
          "query productIds: string",
          "query resellerId: string",
          "query provider: value",
          "query refundStatus: value",
          "query recordType: 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/developerCustomerSerialRoutes.js",
          "services/developerCustomerSerialService.js",
          "services/resellerSalesReportingPolicy.js",
          "services/purchaseReceiptPromotionService.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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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": "Exports all matching authorized records from a stable read-only snapshot; page and limit do not restrict the export to the current screen. All three tables accept dateFrom/dateTo. Customer dates use signup/relationship creation; redeemed serials use redemption and available serials creation; purchases use their source event. Custom calendar bounds are inclusive UTC dates, not Eastern billing buckets. Purchases preserve Purchase Record ID, displayed Order ID and Reseller Order ID separately and can expand a grouped record into multiple item rows. completedRecords counts logical source records/groups, not necessarily CSV lines. With NDJSON, accumulate type:chunk csv fields, require type:complete after commit, and discard partial output on type:error or a disconnected stream. An HTTP 200 before completion is not a successful complete export. CSV remains private, no-store.",
        "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": "all, 1d, 1w, 2w, 1m or custom. Legacy YYYY-MM-DD_to_YYYY-MM-DD is supported. Non-custom presets clear stale calendar dates."
          },
          {
            "name": "dateFrom",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": false,
            "description": "Inclusive UTC calendar start, not the Eastern accounting month."
          },
          {
            "name": "dateTo",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": false,
            "description": "Inclusive UTC calendar end; the SQL upper bound is the next midnight."
          },
          {
            "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": ""
          },
          {
            "in": "header",
            "name": "Accept",
            "schema": {
              "type": "string",
              "enum": [
                "text/csv",
                "application/x-ndjson"
              ]
            },
            "description": "Use application/x-ndjson for progress framing, otherwise receive plain CSV."
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: text/csv.",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/x-ndjson": {
                "schema": {
                  "type": "string",
                  "description": "Newline-delimited chunk, complete or error frames. A chunk contains csv, completedRecords and totalRecords. Completion is required before offering the accumulated CSV."
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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. all, 1d, 1w, 2w, 1m or custom. Legacy YYYY-MM-DD_to_YYYY-MM-DD is supported. Non-custom presets clear stale calendar dates.",
          "query dateFrom: string. Inclusive UTC calendar start, not the Eastern accounting month.",
          "query dateTo: string. Inclusive UTC calendar end; the SQL upper bound is the next midnight.",
          "query productId: integer",
          "query channel: value",
          "query productIds: string",
          "query resellerId: string",
          "query provider: value",
          "query refundStatus: value",
          "query recordType: value",
          "header Accept: string. Use application/x-ndjson for progress framing, otherwise receive plain CSV."
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.",
        "security": [
          {
            "AccountSession": []
          }
        ],
        "x-contract-coverage": "Reviewed field schemas; inspect 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/customerTableDateFilter.js",
          "services/customerExportReadContext.js",
          "services/purchaseExportPager.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 session token",
        "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 session token",
        "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 session token",
        "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 selected developer workspace 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. Workspace readiness requires products.view and all-products scope; storefront readiness requires storefront.view and all-products scope. Product readiness requires products.view, assignment and active-workspace ownership. Workspace billing, settlement, email and partner categories follow their existing view permissions and are not queried for unauthorized roles.",
        "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 session token",
        "x-access-scope": "products.view and all-products scope in the selected developer workspace; restricted billing, settlement, email and partner categories require their matching view permissions.",
        "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",
          "services/developerRbacScopeService.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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 America/New_York calendar month, not an arbitrary requested historical range. Summary/products/activity/charges have compatible /analytics/revenue routes with the same all-products restriction. Customer records require customers.view; order and order-item references are null without orders.view; ledger adjustment references are null without refunds.view. The multi-section overview retains aggregate customer metrics but omits private customer rows and subscription identities without customers.view.",
        "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",
                              "null"
                            ]
                          },
                          "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 session token",
        "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 America/New_York calendar month, not an arbitrary requested historical range. Summary/products/activity/charges have compatible /analytics/revenue routes with the same all-products restriction. Customer records require customers.view; order and order-item references are null without orders.view; ledger adjustment references are null without refunds.view. The multi-section overview retains aggregate customer metrics but omits private customer rows and subscription identities without customers.view.",
        "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 session token",
        "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 America/New_York calendar month, not an arbitrary requested historical range. Summary/products/activity/charges have compatible /analytics/revenue routes with the same all-products restriction. Customer records require customers.view; order and order-item references are null without orders.view; ledger adjustment references are null without refunds.view. The multi-section overview retains aggregate customer metrics but omits private customer rows and subscription identities without customers.view.",
        "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 session token",
        "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",
                              "null"
                            ]
                          },
                          "order_item_id": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "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 session token",
        "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 America/New_York calendar month, not an arbitrary requested historical range. Summary/products/activity/charges have compatible /analytics/revenue routes with the same all-products restriction. Customer records require customers.view; order and order-item references are null without orders.view; ledger adjustment references are null without refunds.view. The multi-section overview retains aggregate customer metrics but omits private customer rows and subscription identities without customers.view.",
        "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 session token",
        "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. Customer identity requires customers.view. Private reasons, ledger descriptions and customer-linked access details are withheld without that permission. order and issue_id are null without orders.view, with linked detail rows withheld. q/search requires both customer and order view permissions; orderId filtering requires orders.view. These checks run before SQL to prevent a hidden-identity search oracle.",
        "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": {
                          "issue_id": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "type": {
                            "enum": [
                              "refund",
                              "dispute"
                            ]
                          },
                          "status": {
                            "type": "string"
                          },
                          "order": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "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 session token",
        "x-access-scope": "analytics.view and all-products workspace scope. Filters never expand the effective developer workspace. refunds.view is also required.",
        "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. Customer identity and free-text details still require customers.view. 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": {
                        "issue_id": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "type": {
                          "enum": [
                            "refund",
                            "dispute"
                          ]
                        },
                        "status": {
                          "type": "string"
                        },
                        "order": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "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 session token",
        "x-access-scope": "analytics.view and all-products workspace scope. Filters never expand the effective developer workspace. refunds.view and orders.view are also required.",
        "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 America/New_York calendar month, not an arbitrary requested historical range. Summary/products/activity/charges have compatible /analytics/revenue routes with the same all-products restriction. Customer records require customers.view; order and order-item references are null without orders.view; ledger adjustment references are null without refunds.view. The multi-section overview retains aggregate customer metrics but omits private customer rows and subscription identities without customers.view.",
        "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",
                              "null"
                            ]
                          },
                          "order_item_id": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "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 session token",
        "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 America/New_York calendar month, not an arbitrary requested historical range. Summary/products/activity/charges have compatible /analytics/revenue routes with the same all-products restriction. Customer records require customers.view; order and order-item references are null without orders.view; ledger adjustment references are null without refunds.view. The multi-section overview retains aggregate customer metrics but omits private customer rows and subscription identities without customers.view.",
        "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 session token",
        "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 America/New_York calendar month, not an arbitrary requested historical range. Summary/products/activity/charges have compatible /analytics/revenue routes with the same all-products restriction. Customer records require customers.view; order and order-item references are null without orders.view; ledger adjustment references are null without refunds.view. The multi-section overview retains aggregate customer metrics but omits private customer rows and subscription identities without customers.view.",
        "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 session token",
        "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 America/New_York calendar month, not an arbitrary requested historical range. Summary/products/activity/charges have compatible /analytics/revenue routes with the same all-products restriction. Customer records require customers.view; order and order-item references are null without orders.view; ledger adjustment references are null without refunds.view. The multi-section overview retains aggregate customer metrics but omits private customer rows and subscription identities without customers.view.",
        "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",
                              "null"
                            ]
                          },
                          "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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": "all, 1d, 1w, 2w, 1m or custom. Legacy YYYY-MM-DD_to_YYYY-MM-DD is supported. Non-custom presets clear stale calendar dates."
          },
          {
            "name": "dateFrom",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": false,
            "description": "Inclusive UTC calendar start, not the Eastern accounting month."
          },
          {
            "name": "dateTo",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": false,
            "description": "Inclusive UTC calendar end; the SQL upper bound is the next midnight."
          },
          {
            "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 session token",
        "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. all, 1d, 1w, 2w, 1m or custom. Legacy YYYY-MM-DD_to_YYYY-MM-DD is supported. Non-custom presets clear stale calendar dates.",
          "query dateFrom: string. Inclusive UTC calendar start, not the Eastern accounting month.",
          "query dateTo: string. Inclusive UTC calendar end; the SQL upper bound is the next midnight.",
          "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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": "all, 1d, 1w, 2w, 1m or custom. Legacy YYYY-MM-DD_to_YYYY-MM-DD is supported. Non-custom presets clear stale calendar dates."
          },
          {
            "name": "dateFrom",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": false,
            "description": "Inclusive UTC calendar start, not the Eastern accounting month."
          },
          {
            "name": "dateTo",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": false,
            "description": "Inclusive UTC calendar end; the SQL upper bound is the next midnight."
          },
          {
            "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 session token",
        "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. all, 1d, 1w, 2w, 1m or custom. Legacy YYYY-MM-DD_to_YYYY-MM-DD is supported. Non-custom presets clear stale calendar dates.",
          "query dateFrom: string. Inclusive UTC calendar start, not the Eastern accounting month.",
          "query dateTo: string. Inclusive UTC calendar end; the SQL upper bound is the next midnight.",
          "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 session token",
        "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": "Exports all matching authorized records from a stable read-only snapshot; page and limit do not restrict the export to the current screen. All three tables accept dateFrom/dateTo. Customer dates use signup/relationship creation; redeemed serials use redemption and available serials creation; purchases use their source event. Custom calendar bounds are inclusive UTC dates, not Eastern billing buckets. Purchases preserve Purchase Record ID, displayed Order ID and Reseller Order ID separately and can expand a grouped record into multiple item rows. completedRecords counts logical source records/groups, not necessarily CSV lines. With NDJSON, accumulate type:chunk csv fields, require type:complete after commit, and discard partial output on type:error or a disconnected stream. An HTTP 200 before completion is not a successful complete export. CSV remains private, no-store.",
        "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": "all, 1d, 1w, 2w, 1m or custom. Legacy YYYY-MM-DD_to_YYYY-MM-DD is supported. Non-custom presets clear stale calendar dates."
          },
          {
            "name": "dateFrom",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": false,
            "description": "Inclusive UTC calendar start, not the Eastern accounting month."
          },
          {
            "name": "dateTo",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": false,
            "description": "Inclusive UTC calendar end; the SQL upper bound is the next midnight."
          },
          {
            "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": ""
          },
          {
            "in": "header",
            "name": "Accept",
            "schema": {
              "type": "string",
              "enum": [
                "text/csv",
                "application/x-ndjson"
              ]
            },
            "description": "Use application/x-ndjson for progress framing, otherwise receive plain CSV."
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: text/csv.",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/x-ndjson": {
                "schema": {
                  "type": "string",
                  "description": "Newline-delimited chunk, complete or error frames. A chunk contains csv, completedRecords and totalRecords. Completion is required before offering the accumulated CSV."
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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. all, 1d, 1w, 2w, 1m or custom. Legacy YYYY-MM-DD_to_YYYY-MM-DD is supported. Non-custom presets clear stale calendar dates.",
          "query dateFrom: string. Inclusive UTC calendar start, not the Eastern accounting month.",
          "query dateTo: string. Inclusive UTC calendar end; the SQL upper bound is the next midnight.",
          "query productId: integer",
          "query status: string",
          "header Accept: string. Use application/x-ndjson for progress framing, otherwise receive plain CSV."
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.",
        "security": [
          {
            "AccountSession": []
          }
        ],
        "x-contract-coverage": "Reviewed field schemas; inspect 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/customerTableDateFilter.js",
          "services/customerExportReadContext.js",
          "services/purchaseExportPager.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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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": "Can initialize a local settlement account, recalculate balances and refresh a configured Stripe Connect account. Not a zero-write uptime probe. payout_ready is an account/destination status, not approval to send, a guaranteed net amount or confirmed bank receipt. No transfer or automatic-execution setting is changed. 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": "currency",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "usd"
            }
          },
          {
            "name": "environment",
            "in": "query",
            "schema": {
              "enum": [
                "live",
                "test"
              ],
              "default": "live"
            }
          }
        ],
        "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 session token",
        "x-access-scope": "billing.view and all-products workspace scope; effective developer ownership.",
        "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/developerSettlementRoutes.js",
          "services/payoutSettlementService.js",
          "services/revenueReportingScope.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 session token",
        "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 session token",
        "x-access-scope": "billing.view and all-products workspace scope; effective developer ownership.",
        "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 session token",
        "x-access-scope": "billing.view and all-products workspace scope; effective developer ownership. Workspace owner only for this setup operation.",
        "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/earnings/adjustments-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/adjustments-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/adjustments-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "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/earnings/recovery/cases": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/cases",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/cases. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "MOR_RECOVERY_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/settlements/earnings/recovery/cases/{id}": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/cases/{id}",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/cases/{id}. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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/earnings/recovery/offsets": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/offsets",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/offsets. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/settlements/earnings/recovery/reserve": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/reserve",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/reserve. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "MOR_RECOVERY_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/settlements/earnings/recovery/statements": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/statements",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/statements. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/settlements/earnings/recovery/summary": {
      "get": {
        "summary": "GET /api/developer/settlements/recovery/summary",
        "description": "Active compatibility alias of GET /api/developer/settlements/recovery/summary. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/morRecoveryService.js"
        ]
      }
    },
    "/api/developer/settlements/earnings/settlements-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/settlements-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/settlements-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "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/earnings/statements-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/statements-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/statements-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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 Eastern calendar 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": "See the linked operation reference for the response contract.",
            "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",
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "period_start": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "period_end": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "marketing_email_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "redemption_overage_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_adjustment_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "developer_service_fee_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "provider_processing_fees_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "non_sale_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_qualifying_basis": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "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": "AccountSession",
        "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": [
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/settlements/earnings/summary-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/summary-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/summary-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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 Eastern calendar 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": "See the linked operation reference for the response contract.",
            "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",
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "period_start": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "period_end": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "marketing_email_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "redemption_overage_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_adjustment_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "developer_service_fee_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "provider_processing_fees_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "non_sale_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_qualifying_basis": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "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": "AccountSession",
        "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": [
          "JOURNAL_SETTLEMENT_TABLES_MISSING"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/journalSettlementService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/settlements/earnings/transactions-v2": {
      "get": {
        "summary": "GET /api/developer/settlements/transactions-v2",
        "description": "Active compatibility alias of GET /api/developer/settlements/transactions-v2. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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": [
          "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/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. Transfer payout_fee records distinguish the original deduction, actual provider fee, prior adjustment, estimated cross-border component and FX quote/settlement. Pending or unclaimed payment is not bank receipt; unreserved fee adjustments can change a later payout.",
        "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, pendingFeeAdjustmentCents.",
            "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
                                },
                                "provider": {
                                  "type": "string"
                                },
                                "payout_fee": {
                                  "anyOf": [
                                    {
                                      "type": "object",
                                      "properties": {
                                        "feeCents": {
                                          "type": "integer",
                                          "minimum": 0
                                        },
                                        "actualFeeCents": {
                                          "anyOf": [
                                            {
                                              "type": "integer",
                                              "minimum": 0
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        },
                                        "adjustmentCents": {
                                          "type": "integer"
                                        },
                                        "differenceCents": {
                                          "anyOf": [
                                            {
                                              "type": "integer"
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        },
                                        "status": {
                                          "type": "string"
                                        },
                                        "feeComponents": {
                                          "type": "array",
                                          "items": {
                                            "type": "object",
                                            "properties": {
                                              "id": {
                                                "type": "string"
                                              },
                                              "kind": {
                                                "type": "string"
                                              },
                                              "basis": {
                                                "type": "string"
                                              },
                                              "amountCents": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "additionalProperties": true
                                          }
                                        },
                                        "crossBorderEstimated": {
                                          "type": "boolean"
                                        },
                                        "crossBorderFeeCents": {
                                          "type": "integer",
                                          "minimum": 0
                                        },
                                        "crossBorderEstimateBasisPoints": {
                                          "anyOf": [
                                            {
                                              "type": "integer",
                                              "minimum": 0
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        },
                                        "fx": {
                                          "anyOf": [
                                            {
                                              "type": "object",
                                              "properties": {
                                                "currency": {
                                                  "type": "string"
                                                },
                                                "localNetMinor": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "actualLocalNetMinor": {
                                                  "anyOf": [
                                                    {
                                                      "type": "integer",
                                                      "minimum": 0
                                                    },
                                                    {
                                                      "type": "null"
                                                    }
                                                  ]
                                                },
                                                "conversionFeeCents": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "actualExchangeRate": {
                                                  "type": "string"
                                                },
                                                "quote": {
                                                  "type": "object",
                                                  "properties": {
                                                    "id": {
                                                      "type": "string"
                                                    },
                                                    "exchangeRate": {
                                                      "type": "string"
                                                    },
                                                    "expiresAt": {
                                                      "type": "string",
                                                      "format": "date-time"
                                                    }
                                                  },
                                                  "additionalProperties": true
                                                },
                                                "settlementVerified": {
                                                  "type": "boolean"
                                                }
                                              },
                                              "additionalProperties": true
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        }
                                      },
                                      "additionalProperties": true
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "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
                      }
                    },
                    "pendingFeeAdjustmentCents": {
                      "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 session token",
        "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",
          "services/developerPayoutFeeDisclosure.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. The 28 columns, in order, are: Batch, Currency, First sale UTC, Last sale UTC, Scheduled run, Batch earnings cents, Batch status, Invoice offset cents, Transfer reference, Net payout cents, Transfer status, Bank reference, Bank status, Original payout fee deduction cents, Actual payout fee cents, Prior fee adjustment cents, Fee status, Cross-border fee estimated, Cross-border estimate cents included, Cross-border estimate basis points, Quoted FX cost USD cents, Recorded exchange rate, Local payout currency, Recorded local net minor units, FX quote expiry UTC, Conversion status, Fee difference cents, Reconciliation status. Net payout cents is the recorded transfer amount, not gross sale proceeds or guaranteed bank receipt. Actual fee and reconciliation fields can be unavailable until the provider record exists; an empty value is not a confirmed zero. Quoted FX cost is already included in its quoted conversion, not an instruction to subtract it twice. Cross-border estimate cents included is already part of the original deduction. Current accounting is USD; Recorded local net minor units instead uses Local payout currency. Conversion status is confirmed only for a verified settlement, expired_quote for an expired or imminent-expiry quote, unavailable for missing/invalid quote expiry, and quoted for a quote outside that expiry boundary. No FX record leaves this column empty. 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 session token",
        "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 session token",
        "x-access-scope": "billing.view and all-products workspace scope; effective developer ownership.",
        "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-email/send-code": {
      "post": {
        "summary": "Send a private verification code to the proposed PayPal payout email",
        "description": "Eight-digit code, fifteen-minute expiry, one-minute resend cooldown and five sends per hour. Sends a transactional email. It does not change the active destination or prove PayPal eligibility. verification:null means the delivery result no longer matches an active request, for example because the provider was switched during sending. Do not mark that email verified or silently resend; reload the saved destination and verification state.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/payout-setup"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: verification.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verification": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "email": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string",
                              "enum": [
                                "pending",
                                "verified",
                                "locked",
                                "expired",
                                "delivery_failed"
                              ]
                            },
                            "expiresAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "resendAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "additionalProperties": true
                        },
                        {
                          "type": "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"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "billing.view, all-products workspace scope and workspace owner. These are destination setup operations, not payment approval or sending.",
        "x-request-fields": [
          "email: string (required)",
          "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": [
          "INVALID_PAYPAL_EMAIL",
          "PAYOUT_EMAIL_NOT_VERIFIED",
          "PAYPAL_COUNTRY_UNSUPPORTED",
          "PAYOUT_EMAIL_COOLDOWN",
          "PAYOUT_EMAIL_RATE_LIMIT",
          "PAYOUT_EMAIL_DELIVERY_FAILED"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "services/developerPayoutDestinationService.js",
          "services/developerPayoutEmailVerificationService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 127,
                    "pattern": "^[\\x21-\\x7e]+$"
                  },
                  "environment": {
                    "type": "string",
                    "enum": [
                      "test",
                      "live"
                    ]
                  }
                },
                "additionalProperties": true,
                "required": [
                  "email"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/settlements/payout-email/verify": {
      "post": {
        "summary": "Verify the proposed PayPal payout email before saving it",
        "description": "Five failed attempts lock this code. A successful verification does not save the payout method: complete payout-method separately.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/payout-setup"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: verification.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verification": {
                      "type": "object",
                      "properties": {
                        "email": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "verified",
                            "locked",
                            "expired",
                            "delivery_failed"
                          ]
                        },
                        "expiresAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "resendAt": {
                          "type": "string",
                          "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"
                }
              }
            }
          },
          "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 session token",
        "x-access-scope": "billing.view, all-products workspace scope and workspace owner. These are destination setup operations, not payment approval or sending.",
        "x-request-fields": [
          "email: string (required)",
          "code: string (required)",
          "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": [
          "INVALID_PAYPAL_EMAIL",
          "PAYOUT_EMAIL_CODE_EXPIRED",
          "PAYOUT_EMAIL_CODE_LOCKED",
          "PAYOUT_EMAIL_CODE_INVALID"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "services/developerPayoutDestinationService.js",
          "services/developerPayoutEmailVerificationService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 127,
                    "pattern": "^[\\x21-\\x7e]+$"
                  },
                  "code": {
                    "type": "string",
                    "pattern": "^[0-9]{8}$"
                  },
                  "environment": {
                    "type": "string",
                    "enum": [
                      "test",
                      "live"
                    ]
                  }
                },
                "additionalProperties": true,
                "required": [
                  "email",
                  "code"
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/settlements/payout-method": {
      "post": {
        "summary": "Select one Stripe or PayPal developer payout destination",
        "description": "For PayPal, verify the SoundSync account and payout email first, provide the registered PayPal country, and confirm account ownership/ability to receive USD. paypalEmail takes precedence over the email alias; an existing saved PayPal email may be reused when neither is sent. Confirmation must be true. Changing a destination can impose a 24-hour wait. In-progress payments block provider switching. PayPal Payouts is approved in production; recipient eligibility, provider requirements and funding still apply. Inbox verification and destination saving do not send money or establish a completed payout. Stripe local settlement does not change USD accounting.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/payout-setup"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: provider, currency, environment, connection.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "provider": {
                      "type": "string",
                      "enum": [
                        "stripe",
                        "paypal"
                      ]
                    },
                    "currency": {
                      "const": "usd"
                    },
                    "environment": {
                      "type": "string"
                    },
                    "connection": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {},
                          "additionalProperties": true
                        },
                        {
                          "type": "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 session token",
        "x-access-scope": "billing.view, all-products workspace scope and workspace owner. These are destination setup operations, not payment approval or sending.",
        "x-request-fields": [
          "provider: stripe | paypal (required)",
          "environment: test | live",
          "paypalEmail: string",
          "email: string. Supported alias for paypalEmail.",
          "paypalAccountCountry: string",
          "confirmPayPalAccount: 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": [
          "PAYPAL_ACCOUNT_CONFIRMATION_REQUIRED",
          "PAYPAL_EMAIL_VERIFICATION_REQUIRED",
          "PAYPAL_ACCOUNT_COUNTRY_REQUIRED",
          "PAYOUT_EMAIL_NOT_VERIFIED",
          "PAYPAL_COUNTRY_UNSUPPORTED",
          "PAYPAL_PAYOUTS_DISABLED",
          "PAYOUT_IN_PROGRESS",
          "STRIPE_USD_PAYOUT_COUNTRY_UNAVAILABLE"
        ],
        "x-source-files": [
          "routes/developerSettlementRoutes.js",
          "services/developerPayoutDestinationService.js",
          "services/developerPayoutEmailVerificationService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "provider": {
                    "type": "string",
                    "enum": [
                      "stripe",
                      "paypal"
                    ]
                  },
                  "environment": {
                    "type": "string",
                    "enum": [
                      "test",
                      "live"
                    ]
                  },
                  "paypalEmail": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 127,
                    "pattern": "^[\\x21-\\x7e]+$"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 127,
                    "pattern": "^[\\x21-\\x7e]+$",
                    "description": "Supported alias for paypalEmail."
                  },
                  "paypalAccountCountry": {
                    "type": "string"
                  },
                  "confirmPayPalAccount": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "provider"
                ],
                "allOf": [
                  {
                    "if": {
                      "properties": {
                        "provider": {
                          "const": "paypal"
                        }
                      },
                      "required": [
                        "provider"
                      ]
                    },
                    "then": {
                      "properties": {
                        "confirmPayPalAccount": {
                          "const": true
                        }
                      },
                      "required": [
                        "confirmPayPalAccount"
                      ]
                    }
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/developer/settlements/payout-readiness": {
      "get": {
        "summary": "Fetch payout readiness.",
        "description": "Can initialize a local settlement account, recalculate balances and refresh a configured Stripe Connect account. Not a zero-write uptime probe. payout_ready is an account/destination status, not approval to send, a guaranteed net amount or confirmed bank receipt. No transfer or automatic-execution setting is changed. 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": "currency",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "usd"
            }
          },
          {
            "name": "environment",
            "in": "query",
            "schema": {
              "enum": [
                "live",
                "test"
              ],
              "default": "live"
            }
          }
        ],
        "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 session token",
        "x-access-scope": "billing.view and all-products workspace scope; effective developer ownership.",
        "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/developerSettlementRoutes.js",
          "services/payoutSettlementService.js",
          "services/revenueReportingScope.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 session token",
        "x-access-scope": "billing.view and all-products workspace scope; effective developer ownership.",
        "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/payouts/bank-payouts": {
      "get": {
        "summary": "GET /api/developer/settlements/bank-payouts",
        "description": "Active compatibility alias of GET /api/developer/settlements/bank-payouts. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/connectPayoutService.js"
        ]
      }
    },
    "/api/developer/settlements/payouts/history": {
      "get": {
        "summary": "GET /api/developer/settlements/history",
        "description": "Active compatibility alias of GET /api/developer/settlements/history. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. Transfer payout_fee records distinguish the original deduction, actual provider fee, prior adjustment, estimated cross-border component and FX quote/settlement. Pending or unclaimed payment is not bank receipt; unreserved fee adjustments can change a later payout.",
        "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": "See the linked operation reference for the response contract.",
            "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
                                },
                                "provider": {
                                  "type": "string"
                                },
                                "payout_fee": {
                                  "anyOf": [
                                    {
                                      "type": "object",
                                      "properties": {
                                        "feeCents": {
                                          "type": "integer",
                                          "minimum": 0
                                        },
                                        "actualFeeCents": {
                                          "anyOf": [
                                            {
                                              "type": "integer",
                                              "minimum": 0
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        },
                                        "adjustmentCents": {
                                          "type": "integer"
                                        },
                                        "differenceCents": {
                                          "anyOf": [
                                            {
                                              "type": "integer"
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        },
                                        "status": {
                                          "type": "string"
                                        },
                                        "feeComponents": {
                                          "type": "array",
                                          "items": {
                                            "type": "object",
                                            "properties": {
                                              "id": {
                                                "type": "string"
                                              },
                                              "kind": {
                                                "type": "string"
                                              },
                                              "basis": {
                                                "type": "string"
                                              },
                                              "amountCents": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "additionalProperties": true
                                          }
                                        },
                                        "crossBorderEstimated": {
                                          "type": "boolean"
                                        },
                                        "crossBorderFeeCents": {
                                          "type": "integer",
                                          "minimum": 0
                                        },
                                        "crossBorderEstimateBasisPoints": {
                                          "anyOf": [
                                            {
                                              "type": "integer",
                                              "minimum": 0
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        },
                                        "fx": {
                                          "anyOf": [
                                            {
                                              "type": "object",
                                              "properties": {
                                                "currency": {
                                                  "type": "string"
                                                },
                                                "localNetMinor": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "actualLocalNetMinor": {
                                                  "anyOf": [
                                                    {
                                                      "type": "integer",
                                                      "minimum": 0
                                                    },
                                                    {
                                                      "type": "null"
                                                    }
                                                  ]
                                                },
                                                "conversionFeeCents": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "actualExchangeRate": {
                                                  "type": "string"
                                                },
                                                "quote": {
                                                  "type": "object",
                                                  "properties": {
                                                    "id": {
                                                      "type": "string"
                                                    },
                                                    "exchangeRate": {
                                                      "type": "string"
                                                    },
                                                    "expiresAt": {
                                                      "type": "string",
                                                      "format": "date-time"
                                                    }
                                                  },
                                                  "additionalProperties": true
                                                },
                                                "settlementVerified": {
                                                  "type": "boolean"
                                                }
                                              },
                                              "additionalProperties": true
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        }
                                      },
                                      "additionalProperties": true
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "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
                      }
                    },
                    "pendingFeeAdjustmentCents": {
                      "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/payoutHistoryReportingService.js",
          "services/revenueReportingScope.js",
          "services/developerPayoutFeeDisclosure.js"
        ]
      }
    },
    "/api/developer/settlements/payouts/history/export.csv": {
      "get": {
        "summary": "GET /api/developer/settlements/history/export.csv",
        "description": "Active compatibility alias of GET /api/developer/settlements/history/export.csv. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. The 28 columns, in order, are: Batch, Currency, First sale UTC, Last sale UTC, Scheduled run, Batch earnings cents, Batch status, Invoice offset cents, Transfer reference, Net payout cents, Transfer status, Bank reference, Bank status, Original payout fee deduction cents, Actual payout fee cents, Prior fee adjustment cents, Fee status, Cross-border fee estimated, Cross-border estimate cents included, Cross-border estimate basis points, Quoted FX cost USD cents, Recorded exchange rate, Local payout currency, Recorded local net minor units, FX quote expiry UTC, Conversion status, Fee difference cents, Reconciliation status. Net payout cents is the recorded transfer amount, not gross sale proceeds or guaranteed bank receipt. Actual fee and reconciliation fields can be unavailable until the provider record exists; an empty value is not a confirmed zero. Quoted FX cost is already included in its quoted conversion, not an instruction to subtract it twice. Cross-border estimate cents included is already part of the original deduction. Current accounting is USD; Recorded local net minor units instead uses Local payout currency. Conversion status is confirmed only for a verified settlement, expired_quote for an expired or imminent-expiry quote, unavailable for missing/invalid quote expiry, and quoted for a quote outside that expiry boundary. No FX record leaves this column empty. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/payoutHistoryReportingService.js",
          "services/revenueReportingScope.js"
        ]
      }
    },
    "/api/developer/settlements/payouts/summary": {
      "get": {
        "summary": "GET /api/developer/settlements/summary",
        "description": "Active compatibility alias of GET /api/developer/settlements/summary. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. The summary selects the upcoming payout run, not the oldest unpaid run used by owner payment preparation. available_cents belongs to that selected sales period; held_cents can include unpaid earnings outside it or on hold. owed_cents covers the scoped unpaid balance across periods and is not the forecast net or permission to send. unresolved_source_entries/cents identify historical entries without complete order/environment evidence, excluded from confirmed payable totals. payoutForecast is an estimate for the selected Eastern period, not payout eligibility or permission to send: readyToSend is always false. It keeps known sales/usage visible while processingKnown:false leaves processingCents, totalNonSaleCents and netBeforePayoutFeesCents null. A negative net produces amountDueCents rather than a negative transfer. payoutFeePreview can have basis:period_forecast and forecastOnly:true; it is not a completed payment. 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. payoutFeePreview is a read-only projection or prepared amount, not payment execution. The next-run estimate can include recorded earnings that mature by that run. USD accounting, local payout currency, quoted FX cost, estimated provider fees and bank receipt are separate facts. feeComponents preserve each provider component basis and USD-cent amount; actualFeeCents and signed differenceCents are supplied when reconciliation records are available.",
        "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": "See the linked operation reference for the response contract.",
            "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."
                        },
                        "owed_cents": {
                          "type": [
                            "integer",
                            "string"
                          ],
                          "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                        },
                        "source_model": {
                          "type": "string",
                          "enum": [
                            "journal",
                            "legacy"
                          ]
                        },
                        "unresolved_source_entries": {
                          "type": "integer"
                        },
                        "unresolved_source_cents": {
                          "type": [
                            "integer",
                            "string"
                          ],
                          "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                        },
                        "accounting_adjustment_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",
                          "description": "Nominal wait in days. Fixed half-month windows govern eligibility, including short February; this is not an exact rolling hold."
                        },
                        "payout_window_policy": {
                          "type": "string"
                        },
                        "hold_is_approximate": {
                          "type": "boolean"
                        },
                        "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."
                    },
                    "payoutForecast": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "const": "payout-period-forecast-v1"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "available": {
                          "type": "boolean"
                        },
                        "processingKnown": {
                          "type": "boolean"
                        },
                        "pendingProcessingCount": {
                          "type": "integer"
                        },
                        "salesCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "salesFeeCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "earningsBeforeUsageCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "marketingEmailCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "redemptionCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "minimumCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "serviceCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "knownProcessingCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "processingCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "totalNonSaleCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "netBeforePayoutFeesCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "totalDeductionsBeforePayoutFeeCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "amountDueCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "minimumBasis": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "readyToSend": {
                          "const": false
                        },
                        "period_start": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "period_end": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "runDate": {
                          "type": "string",
                          "format": "date"
                        },
                        "charges": {
                          "type": "object",
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "period_start": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "period_end": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "marketing_email_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "redemption_overage_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_adjustment_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "developer_service_fee_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "provider_processing_fees_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "non_sale_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_qualifying_basis": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        },
                        "feePreview": {
                          "type": "object",
                          "properties": {
                            "basis": {
                              "const": "period_forecast"
                            },
                            "projected": {
                              "type": "boolean"
                            },
                            "forecastOnly": {
                              "type": "boolean"
                            },
                            "status": {
                              "type": "string"
                            },
                            "grossCents": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "netCents": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "feeCents": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "currency": {
                              "type": "string"
                            },
                            "provider": {
                              "type": "string"
                            },
                            "country": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "businessCountry": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "payoutCurrency": {
                              "type": "string"
                            },
                            "message": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    },
                    "payoutFeePreview": {
                      "type": "object",
                      "properties": {
                        "enabled": {
                          "type": "boolean"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "waiting",
                            "setup_required",
                            "unavailable",
                            "prepared",
                            "calculated",
                            "estimated"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "currency": {
                          "const": "usd"
                        },
                        "provider": {
                          "type": "string",
                          "enum": [
                            "stripe",
                            "paypal"
                          ]
                        },
                        "country": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "businessCountry": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "payoutCurrency": {
                          "type": "string"
                        },
                        "estimated": {
                          "type": "boolean"
                        },
                        "projected": {
                          "type": "boolean"
                        },
                        "basis": {
                          "type": "string"
                        },
                        "runDate": {
                          "type": "string"
                        },
                        "eligibleAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "transferIntentId": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 1
                            },
                            {
                              "type": "string",
                              "pattern": "^[1-9][0-9]*$"
                            }
                          ]
                        },
                        "grossCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "billingOffsetCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "adjustmentCents": {
                          "type": "integer"
                        },
                        "roundingCarryCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "feeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "netCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "transferFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "crossBorderFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "settlementFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "feeComponents": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "kind": {
                                "type": "string"
                              },
                              "basis": {
                                "type": "string"
                              },
                              "amountCents": {
                                "type": "integer",
                                "minimum": 0
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "conversionFeeCents": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "recipientConversionIncluded": {
                          "type": "boolean"
                        },
                        "monthlyFeePeriod": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "localNetMinor": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "exchangeRate": {
                          "type": "string"
                        },
                        "totalDeveloperFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "netUsdEquivalentCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "fxFeeTreatment": {
                          "type": "string"
                        },
                        "fxQuoteExpiresAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "fxSettled": {
                          "type": "boolean"
                        },
                        "crossBorderEstimated": {
                          "type": "boolean"
                        },
                        "crossBorderEstimateBasisPoints": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "actualFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "differenceCents": {
                          "type": "integer"
                        },
                        "feeReconciled": {
                          "type": "boolean"
                        },
                        "reconciliationStatus": {
                          "type": "string"
                        },
                        "feeDisclosure": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "calculation": {
                          "type": "string"
                        },
                        "period_start": {
                          "type": "string"
                        },
                        "period_end": {
                          "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/transferIntentService.js",
          "services/externalPartnerSalesReportingService.js",
          "services/payoutPeriodForecastService.js",
          "services/actualProcessingFeeService.js",
          "services/developerPayoutPreviewService.js",
          "services/developerStripeLocalPayoutService.js",
          "services/developerPayoutUpfrontRates.js",
          "services/developerPayoutFeeDisclosure.js"
        ]
      }
    },
    "/api/developer/settlements/payouts/transfers": {
      "get": {
        "summary": "GET /api/developer/settlements/transfers",
        "description": "Active compatibility alias of GET /api/developer/settlements/transfers. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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-source-files": [
          "routes/developerSettlementRoutes.js",
          "middleware/developerTeamAuth.js",
          "services/transferIntentService.js"
        ]
      }
    },
    "/api/developer/settlements/payouts/transfers/{id}": {
      "get": {
        "summary": "GET /api/developer/settlements/transfers/{id}",
        "description": "Active compatibility alias of GET /api/developer/settlements/transfers/{id}. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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": "See the linked operation reference for the response contract.",
            "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": "AccountSession",
        "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/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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 Eastern calendar 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",
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "period_start": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "period_end": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "marketing_email_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "redemption_overage_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_adjustment_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "developer_service_fee_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "provider_processing_fees_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "non_sale_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_qualifying_basis": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "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 session token",
        "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 Eastern calendar 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. The summary selects the upcoming payout run, not the oldest unpaid run used by owner payment preparation. available_cents belongs to that selected sales period; held_cents can include unpaid earnings outside it or on hold. owed_cents covers the scoped unpaid balance across periods and is not the forecast net or permission to send. unresolved_source_entries/cents identify historical entries without complete order/environment evidence, excluded from confirmed payable totals. payoutForecast is an estimate for the selected Eastern period, not payout eligibility or permission to send: readyToSend is always false. It keeps known sales/usage visible while processingKnown:false leaves processingCents, totalNonSaleCents and netBeforePayoutFeesCents null. A negative net produces amountDueCents rather than a negative transfer. payoutFeePreview can have basis:period_forecast and forecastOnly:true; it is not a completed payment. 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. payoutFeePreview is a read-only projection or prepared amount, not payment execution. The next-run estimate can include recorded earnings that mature by that run. USD accounting, local payout currency, quoted FX cost, estimated provider fees and bank receipt are separate facts. feeComponents preserve each provider component basis and USD-cent amount; actualFeeCents and signed differenceCents are supplied when reconciliation records are available.",
        "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, payoutForecast, payoutFeePreview.",
            "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."
                        },
                        "owed_cents": {
                          "type": [
                            "integer",
                            "string"
                          ],
                          "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                        },
                        "source_model": {
                          "type": "string",
                          "enum": [
                            "journal",
                            "legacy"
                          ]
                        },
                        "unresolved_source_entries": {
                          "type": "integer"
                        },
                        "unresolved_source_cents": {
                          "type": [
                            "integer",
                            "string"
                          ],
                          "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                        },
                        "accounting_adjustment_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",
                          "description": "Nominal wait in days. Fixed half-month windows govern eligibility, including short February; this is not an exact rolling hold."
                        },
                        "payout_window_policy": {
                          "type": "string"
                        },
                        "hold_is_approximate": {
                          "type": "boolean"
                        },
                        "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."
                    },
                    "payoutForecast": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "const": "payout-period-forecast-v1"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "available": {
                          "type": "boolean"
                        },
                        "processingKnown": {
                          "type": "boolean"
                        },
                        "pendingProcessingCount": {
                          "type": "integer"
                        },
                        "salesCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "salesFeeCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "earningsBeforeUsageCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "marketingEmailCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "redemptionCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "minimumCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "serviceCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "knownProcessingCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "processingCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "totalNonSaleCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "netBeforePayoutFeesCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "totalDeductionsBeforePayoutFeeCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "amountDueCents": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "minimumBasis": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "readyToSend": {
                          "const": false
                        },
                        "period_start": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "period_end": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "runDate": {
                          "type": "string",
                          "format": "date"
                        },
                        "charges": {
                          "type": "object",
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "period_start": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "period_end": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "marketing_email_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "redemption_overage_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_adjustment_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "developer_service_fee_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "provider_processing_fees_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "non_sale_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_qualifying_basis": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        },
                        "feePreview": {
                          "type": "object",
                          "properties": {
                            "basis": {
                              "const": "period_forecast"
                            },
                            "projected": {
                              "type": "boolean"
                            },
                            "forecastOnly": {
                              "type": "boolean"
                            },
                            "status": {
                              "type": "string"
                            },
                            "grossCents": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "netCents": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "feeCents": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "currency": {
                              "type": "string"
                            },
                            "provider": {
                              "type": "string"
                            },
                            "country": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "businessCountry": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "payoutCurrency": {
                              "type": "string"
                            },
                            "message": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    },
                    "payoutFeePreview": {
                      "type": "object",
                      "properties": {
                        "enabled": {
                          "type": "boolean"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "waiting",
                            "setup_required",
                            "unavailable",
                            "prepared",
                            "calculated",
                            "estimated"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "currency": {
                          "const": "usd"
                        },
                        "provider": {
                          "type": "string",
                          "enum": [
                            "stripe",
                            "paypal"
                          ]
                        },
                        "country": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "businessCountry": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "payoutCurrency": {
                          "type": "string"
                        },
                        "estimated": {
                          "type": "boolean"
                        },
                        "projected": {
                          "type": "boolean"
                        },
                        "basis": {
                          "type": "string"
                        },
                        "runDate": {
                          "type": "string"
                        },
                        "eligibleAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "transferIntentId": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 1
                            },
                            {
                              "type": "string",
                              "pattern": "^[1-9][0-9]*$"
                            }
                          ]
                        },
                        "grossCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "billingOffsetCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "adjustmentCents": {
                          "type": "integer"
                        },
                        "roundingCarryCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "feeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "netCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "transferFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "crossBorderFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "monthlyFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "settlementFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "feeComponents": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "kind": {
                                "type": "string"
                              },
                              "basis": {
                                "type": "string"
                              },
                              "amountCents": {
                                "type": "integer",
                                "minimum": 0
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "conversionFeeCents": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "recipientConversionIncluded": {
                          "type": "boolean"
                        },
                        "monthlyFeePeriod": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "localNetMinor": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "exchangeRate": {
                          "type": "string"
                        },
                        "totalDeveloperFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "netUsdEquivalentCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "fxFeeTreatment": {
                          "type": "string"
                        },
                        "fxQuoteExpiresAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "fxSettled": {
                          "type": "boolean"
                        },
                        "crossBorderEstimated": {
                          "type": "boolean"
                        },
                        "crossBorderEstimateBasisPoints": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "actualFeeCents": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "differenceCents": {
                          "type": "integer"
                        },
                        "feeReconciled": {
                          "type": "boolean"
                        },
                        "reconciliationStatus": {
                          "type": "string"
                        },
                        "feeDisclosure": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "calculation": {
                          "type": "string"
                        },
                        "period_start": {
                          "type": "string"
                        },
                        "period_end": {
                          "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 session token",
        "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",
          "services/payoutPeriodForecastService.js",
          "services/actualProcessingFeeService.js",
          "services/developerPayoutPreviewService.js",
          "services/developerStripeLocalPayoutService.js",
          "services/developerPayoutUpfrontRates.js",
          "services/developerPayoutFeeDisclosure.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 Eastern calendar 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",
                          "properties": {
                            "available": {
                              "type": "boolean"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "period_start": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "period_end": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "marketing_email_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "redemption_overage_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_adjustment_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "developer_service_fee_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "provider_processing_fees_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "non_sale_charges_cents": {
                              "type": [
                                "integer",
                                "string"
                              ],
                              "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
                            },
                            "minimum_qualifying_basis": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "marketing_emails": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                },
                                "rate_cents_per_1000": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "external_redemptions": {
                              "type": "object",
                              "properties": {
                                "quantity": {
                                  "type": "integer"
                                },
                                "billable": {
                                  "type": "integer"
                                },
                                "free_used": {
                                  "type": "integer"
                                },
                                "free_limit": {
                                  "type": "integer"
                                },
                                "free_used_in_period": {
                                  "type": "integer"
                                },
                                "allowance_months": {
                                  "type": "integer"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "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 session token",
        "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 Eastern calendar 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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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/popup-rewards": {
      "get": {
        "summary": "Choose owned one-time products and active reward templates for popup campaigns",
        "description": "Returns developer-owned giveaway products and active post_purchase_coupon offer templates. A popup signup earns the same type of customer-bound coupon without a purchase. Saving siteStructure.popups validates reward ownership and availability. Built-in page and footer newsletter settings are independent.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/storefront-management"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: products, offers.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "products": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "anyOf": [
                              {
                                "type": "integer",
                                "minimum": 1
                              },
                              {
                                "type": "string",
                                "pattern": "^[1-9][0-9]*$"
                              }
                            ]
                          },
                          "name": {
                            "type": "string"
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "offers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "anyOf": [
                              {
                                "type": "integer",
                                "minimum": 1
                              },
                              {
                                "type": "string",
                                "pattern": "^[1-9][0-9]*$"
                              }
                            ]
                          },
                          "title": {
                            "type": "string"
                          },
                          "discount_type": {
                            "type": "string"
                          },
                          "discount_value": {
                            "type": [
                              "number",
                              "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"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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/storefrontPopupService.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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 selected 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. Workspace readiness requires products.view and all-products scope; storefront readiness requires storefront.view and all-products scope. Product readiness requires products.view, assignment and active-workspace ownership. Workspace billing, settlement, email and partner categories follow their existing view permissions and are not queried for unauthorized roles.",
        "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 session token",
        "x-access-scope": "storefront.view and all-products scope in the selected 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/developerReadinessRoutes.js",
          "services/developerReadinessService.js",
          "services/developerReadinessSummaryService.js",
          "services/developerRbacScopeService.js"
        ]
      }
    },
    "/api/developer/subscription-bundles": {
      "get": {
        "summary": "List bundle definitions in the effective developer workspace.",
        "description": "products.view and all-products scope. Editing an existing legacy bundle requires products.edit and all-products scope. Creating a selected-products bundle still checks assignment for every included product. The reporting summary additionally requires analytics.view and all-products scope. These guards do not change accepted subscription terms or accounting. 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 session token",
        "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. Editing an existing legacy bundle requires products.edit and all-products scope. Creating a selected-products bundle still checks assignment for every included product. The reporting summary additionally requires analytics.view and all-products scope. These guards do not change accepted subscription terms or accounting. 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 session token",
        "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. Editing an existing legacy bundle requires products.edit and all-products scope. Creating a selected-products bundle still checks assignment for every included product. The reporting summary additionally requires analytics.view and all-products scope. These guards do not change accepted subscription terms or accounting. 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 session token",
        "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": "Editing an existing legacy bundle requires products.edit and all-products scope. Creating a selected-products bundle still checks assignment for every included product. The reporting summary additionally requires analytics.view and all-products scope. These guards do not change accepted subscription terms or accounting. 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 session token",
        "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. Editing an existing legacy bundle requires products.edit and all-products scope. Creating a selected-products bundle still checks assignment for every included product. The reporting summary additionally requires analytics.view and all-products scope. These guards do not change accepted subscription terms or accounting. 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 session token",
        "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. Editing an existing legacy bundle requires products.edit and all-products scope. Creating a selected-products bundle still checks assignment for every included product. The reporting summary additionally requires analytics.view and all-products scope. These guards do not change accepted subscription terms or accounting. 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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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. Public HTTP(S) webhook destinations must not contain URL credentials or resolve to private/reserved addresses. Test delivery pins validated DNS, does not follow redirects and returns at most 500 response characters from a bounded response read. A redirect status is returned for inspection; it is not followed with the webhook secret.",
        "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"
                }
              }
            }
          },
          "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"
                }
              }
            }
          },
          "504": {
            "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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",
          "utils/webhookDestination.js",
          "utils/publicNetworkAddress.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. Public HTTP(S) webhook destinations must not contain URL credentials or resolve to private/reserved addresses. Test delivery pins validated DNS, does not follow redirects and returns at most 500 response characters from a bounded response read. A redirect status is returned for inspection; it is not followed with the webhook secret.",
        "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"
                }
              }
            }
          },
          "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"
                }
              }
            }
          },
          "504": {
            "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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",
          "utils/webhookDestination.js",
          "utils/publicNetworkAddress.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. Public HTTP(S) webhook destinations must not contain URL credentials or resolve to private/reserved addresses. Test delivery pins validated DNS, does not follow redirects and returns at most 500 response characters from a bounded response read. A redirect status is returned for inspection; it is not followed with the webhook secret.",
        "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"
                }
              }
            }
          },
          "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"
                }
              }
            }
          },
          "504": {
            "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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",
          "utils/webhookDestination.js",
          "utils/publicNetworkAddress.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. Public HTTP(S) webhook destinations must not contain URL credentials or resolve to private/reserved addresses. Test delivery pins validated DNS, does not follow redirects and returns at most 500 response characters from a bounded response read. A redirect status is returned for inspection; it is not followed with the webhook secret.",
        "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"
                }
              }
            }
          },
          "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"
                }
              }
            }
          },
          "504": {
            "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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",
          "utils/webhookDestination.js",
          "utils/publicNetworkAddress.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. Public HTTP(S) webhook destinations must not contain URL credentials or resolve to private/reserved addresses. Test delivery pins validated DNS, does not follow redirects and returns at most 500 response characters from a bounded response read. A redirect status is returned for inspection; it is not followed with the webhook secret.",
        "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"
                }
              }
            }
          },
          "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"
                }
              }
            }
          },
          "504": {
            "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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",
          "utils/webhookDestination.js",
          "utils/publicNetworkAddress.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. Current SoundSync-wide suspension blocks new download authorization with 403 CUSTOMER_ACCOUNT_RESTRICTED. A store closure affects only that store. Already issued storage URLs expire independently.",
        "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 session token + 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-error-codes": [
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "CUSTOMER_STORE_CLOSED",
          "SESSION_VERIFICATION_UNAVAILABLE"
        ],
        "x-source-files": [
          "routes/downloadRoutes.js",
          "controllers/downloadController.js",
          "services/customerDownloadAccountAccess.js",
          "services/customerAccountRestrictionService.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. Current SoundSync-wide suspension blocks new download authorization with 403 CUSTOMER_ACCOUNT_RESTRICTED. A store closure affects only that store. Already issued storage URLs expire independently.",
        "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 session token + 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-error-codes": [
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "CUSTOMER_STORE_CLOSED",
          "SESSION_VERIFICATION_UNAVAILABLE"
        ],
        "x-source-files": [
          "routes/downloadRoutes.js",
          "controllers/downloadController.js",
          "services/customerDownloadAccountAccess.js",
          "services/customerAccountRestrictionService.js"
        ]
      }
    },
    "/api/email-change/verify": {
      "get": {
        "summary": "GET /api/account/email-change/verify. The private email-change proof has the same confirmation semantics at both mounts. GET displays a form without consuming it; POST confirms the change.",
        "description": "Active compatibility alias of GET /api/account/email-change/verify. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. The private email-change proof has the same confirmation semantics at both mounts. GET displays a form without consuming it; POST confirms the change. 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": "See the linked operation reference for the response contract.",
            "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": "Private email-change token authorizes viewing its confirmation form only; GET does not consume the token or change the address.",
        "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/accountEmailVerificationRoutes.js",
          "controllers/accountController.js",
          "services/customerInformationUpdateService.js"
        ]
      },
      "post": {
        "summary": "POST /api/account/email-change/verify. The private email-change proof has the same confirmation semantics at both mounts. GET displays a form without consuming it; POST confirms the change.",
        "description": "Active compatibility alias of POST /api/account/email-change/verify. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. The private email-change proof has the same confirmation semantics at both mounts. GET displays a form without consuming it; POST confirms the change. 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": "See the linked operation reference for the response contract.",
            "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": "Private email-change confirmation token; POST confirms the pending change without requiring a sign-in session.",
        "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/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/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": "Requires a current customer-account session, either shared SoundSync sign-in or an authorized store-scoped customer session. A bare legacy serial/download proof returns 403 CUSTOMER_ACCOUNT_REQUIRED. The query names token, download_token and libraryToken are transport aliases where documented, not permission to substitute a different token type. Prefer Authorization: Bearer to keep credentials out of URLs. 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. SoundSync-wide customer suspension returns 403 CUSTOMER_ACCOUNT_RESTRICTED, including for an existing shared account session; store closure remains store-scoped. Shared library tokens follow their own token/ownership checks and do not replace required customer-account sign-in.",
        "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": "Account Bearer session token",
        "x-access-scope": "Current customer-account session and verified customer ownership. Store-scoped sessions remain confined to their storefront; a legacy serial/download token is not account sign-in.",
        "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": [
          {
            "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",
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "CUSTOMER_STORE_CLOSED",
          "CUSTOMER_ACCOUNT_REQUIRED"
        ],
        "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/integrations/commerce/fastspring/{publicId}/fulfill/{mappingId}": {
      "post": {
        "summary": "Reserve FastSpring quantity-based license keys",
        "description": "Returns the same reserved keys for repeated order/reference/quantity requests. A reservation is not an entitlement or successful activation. Test keys are simulated. Keep this credential on FastSpring servers, not in the plugin, customer email or browser. Ordinary offline-grace behavior on already disconnected devices is unchanged.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/commerce-integrations"
        },
        "parameters": [
          {
            "name": "publicId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mappingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200: Inspect the response schema and conditional states.",
            "content": {
              "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 authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "FastSpringFulfillment",
        "x-access-scope": "Active connection and owned eligible mapping; matching authenticated completed event is separately required.",
        "x-request-fields": [
          "reference: string (required)",
          "email: string (required)",
          "name: string",
          "quantity: integer (required)",
          "subscription: string"
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.",
        "security": [
          {
            "FastSpringFulfillment": []
          }
        ],
        "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.",
        "x-source-files": [
          "routes/commerceIntegrationRoutes.js",
          "services/commerceIntegrationService.js",
          "services/commerceConnectors/index.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "reference": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "name": {
                    "type": "string"
                  },
                  "quantity": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "subscription": {
                    "type": "string"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "reference",
                  "email",
                  "quantity"
                ]
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reference": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "name": {
                    "type": "string"
                  },
                  "quantity": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "subscription": {
                    "type": "string"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "reference",
                  "email",
                  "quantity"
                ]
              }
            }
          }
        }
      }
    },
    "/api/integrations/commerce/fastspring/{publicId}/webhook": {
      "post": {
        "summary": "Receive authenticated fastspring purchase and access events",
        "description": "External one-time perpetual licensing only. No external gross sales, payment processing, tax, monetary refund or payout balance is created in SoundSync. Test connections simulate keys without usable licenses or financial entries. Confirmed Live units record idempotent external-redemption usage. Configuration checks are not hosted provider tests. Setup responses contain private credentials and must not be logged, shared or cached. All responses use Cache-Control: no-store. Use the provider-generated payload, not a hand-built success flag. Exact raw bytes are required for signature verification. Full supported returns revoke only the original grants; partial/ambiguous returns require review. A 503 requests original-event retry; duplicate/conflicting events are reconciled. Uses X-FS-Signature HMAC-SHA256 and expanded events.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/commerce-integrations"
        },
        "parameters": [
          {
            "name": "publicId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200: Inspect the response schema and conditional states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "status": {
                            "type": "string"
                          },
                          "code": {
                            "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": "FastSpringSignature",
        "x-access-scope": "Connection-bound provider authentication and environment; raw-byte signatures/merchant verification 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": [
          {
            "FastSpringSignature": []
          }
        ],
        "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.",
        "x-source-files": [
          "routes/commerceIntegrationRoutes.js",
          "services/commerceIntegrationService.js",
          "services/commerceConnectors/index.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/integrations/commerce/gumroad/{publicId}/webhook/{secret}": {
      "post": {
        "summary": "Receive authenticated gumroad purchase and access events",
        "description": "External one-time perpetual licensing only. No external gross sales, payment processing, tax, monetary refund or payout balance is created in SoundSync. Test connections simulate keys without usable licenses or financial entries. Confirmed Live units record idempotent external-redemption usage. Configuration checks are not hosted provider tests. Setup responses contain private credentials and must not be logged, shared or cached. All responses use Cache-Control: no-store. Use the provider-generated payload, not a hand-built success flag. Exact raw bytes are required for signature verification. Full supported returns revoke only the original grants; partial/ambiguous returns require review. A 503 requests original-event retry; duplicate/conflicting events are reconciled. The URL secret authenticates notification hints; saved merchant credentials independently verify the sale, seller, product and current refund/access state. Treat the entire URL as private.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/commerce-integrations"
        },
        "parameters": [
          {
            "name": "publicId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "secret",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200: Inspect the response schema and conditional states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "status": {
                            "type": "string"
                          },
                          "code": {
                            "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": "Private generated URL secret plus independent merchant API sale verification; no account Bearer token",
        "x-access-scope": "Connection-bound provider authentication and environment; raw-byte signatures/merchant verification apply. The required secret path parameter is private authentication, not a public anonymous grant.",
        "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/commerceIntegrationRoutes.js",
          "services/commerceIntegrationService.js",
          "services/commerceConnectors/index.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": true
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/integrations/commerce/woocommerce/{publicId}/webhook": {
      "post": {
        "summary": "Receive authenticated woocommerce purchase and access events",
        "description": "External one-time perpetual licensing only. No external gross sales, payment processing, tax, monetary refund or payout balance is created in SoundSync. Test connections simulate keys without usable licenses or financial entries. Confirmed Live units record idempotent external-redemption usage. Configuration checks are not hosted provider tests. Setup responses contain private credentials and must not be logged, shared or cached. All responses use Cache-Control: no-store. Use the provider-generated payload, not a hand-built success flag. Exact raw bytes are required for signature verification. Full supported returns revoke only the original grants; partial/ambiguous returns require review. A 503 requests original-event retry; duplicate/conflicting events are reconciled. Uses X-WC-Webhook-Signature HMAC-SHA256 and matching X-WC-Webhook-Source. An unsigned form registration ping returns ok:true,ping:true but never processes an order or grants access.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/commerce-integrations"
        },
        "parameters": [
          {
            "name": "publicId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200: Inspect the response schema and conditional states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "status": {
                            "type": "string"
                          },
                          "code": {
                            "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": "WooCommerceSignature",
        "x-access-scope": "Connection-bound provider authentication and environment; raw-byte signatures/merchant verification 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": [
          {
            "WooCommerceSignature": []
          }
        ],
        "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.",
        "x-source-files": [
          "routes/commerceIntegrationRoutes.js",
          "services/commerceIntegrationService.js",
          "services/commerceConnectors/index.js"
        ],
        "x-source-revision": "daf41b22a5a5c9c2c988fedfdcdc12e8f5b9247b",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/library": {
      "get": {
        "summary": "Return the portal/library payload for a signed-in customer account.",
        "description": "Requires a current customer-account session, either shared SoundSync sign-in or an authorized store-scoped customer session. A bare legacy serial/download proof returns 403 CUSTOMER_ACCOUNT_REQUIRED. The query names token, download_token and libraryToken are transport aliases where documented, not permission to substitute a different token type. Prefer Authorization: Bearer to keep credentials out of URLs. 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. SoundSync-wide customer suspension returns 403 CUSTOMER_ACCOUNT_RESTRICTED, including for an existing shared account session; store closure remains store-scoped. Shared library tokens follow their own token/ownership checks and do not replace required customer-account sign-in. 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": "Account Bearer session token",
        "x-access-scope": "Current customer-account session and verified customer ownership. Store-scoped sessions remain confined to their storefront; a legacy serial/download token is not account sign-in.",
        "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": [
          {
            "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",
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "CUSTOMER_STORE_CLOSED",
          "CUSTOMER_ACCOUNT_REQUIRED"
        ],
        "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 session token",
        "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": "Requires a current customer-account session, either shared SoundSync sign-in or an authorized store-scoped customer session. A bare legacy serial/download proof returns 403 CUSTOMER_ACCOUNT_REQUIRED. The query names token, download_token and libraryToken are transport aliases where documented, not permission to substitute a different token type. Prefer Authorization: Bearer to keep credentials out of URLs. 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. SoundSync-wide customer suspension returns 403 CUSTOMER_ACCOUNT_RESTRICTED, including for an existing shared account session; store closure remains store-scoped. Shared library tokens follow their own token/ownership checks and do not replace required customer-account sign-in.",
        "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": "Account Bearer session token",
        "x-access-scope": "Current customer-account session and verified customer ownership. Store-scoped sessions remain confined to their storefront; a legacy serial/download token is not account sign-in.",
        "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": [
          {
            "AccountSession": []
          }
        ],
        "x-contract-coverage": "Reviewed 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",
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "CUSTOMER_STORE_CLOSED",
          "CUSTOMER_ACCOUNT_REQUIRED"
        ],
        "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}/machines/{activationId}/deactivate": {
      "post": {
        "summary": "Deactivate one current owned device, preserving the license and other devices",
        "description": "kind is serial or entitlement. Read machines[].activationId and generation from the current library; generation is a stale-view check, not authorization. Reload on 409. This is distinct from a full activation reset/cooldown, refund and offline-grace expiry. An already deactivated device can return deactivated:false. 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. SoundSync-wide customer suspension returns 403 CUSTOMER_ACCOUNT_RESTRICTED, including for an existing shared account session; store closure remains store-scoped. Shared library tokens follow their own token/ownership checks and do not replace required customer-account sign-in.",
        "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": "activationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "storefront",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: deactivated, message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deactivated": {
                      "type": "boolean"
                    },
                    "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 session token",
        "x-access-scope": "Signed-in customer account, owned serial/entitlement and device; a store-only session remains bound to its developer. Shared download links cannot mutate devices.",
        "x-request-fields": [
          "query storefront: string",
          "expectedGeneration: 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": [
          "MACHINE_CONFIRMATION_REQUIRED",
          "MACHINE_STATE_CHANGED",
          "LICENSE_STATE_CHANGED",
          "CUSTOMER_STORE_CLOSED",
          "STOREFRONT_SESSION_SCOPE",
          "SESSION_VERIFICATION_UNAVAILABLE",
          "LIBRARY_SESSION_REVOKED",
          "CUSTOMER_ACCOUNT_RESTRICTED"
        ],
        "x-source-files": [
          "routes/libraryRoutes.js",
          "controllers/libraryController.js",
          "services/customerLicenseMachineService.js",
          "services/customerLibraryIdentityService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expectedGeneration": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{64}$"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "expectedGeneration"
                ]
              }
            }
          }
        }
      }
    },
    "/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. SoundSync-wide customer suspension returns 403 CUSTOMER_ACCOUNT_RESTRICTED, including for an existing shared account session; store closure remains store-scoped. Shared library tokens follow their own token/ownership checks and do not replace required customer-account sign-in.",
        "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 session token",
        "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",
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "CUSTOMER_STORE_CLOSED"
        ],
        "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. Requires a current customer-account session, either shared SoundSync sign-in or an authorized store-scoped customer session. A bare legacy serial/download proof returns 403 CUSTOMER_ACCOUNT_REQUIRED. The query names token, download_token and libraryToken are transport aliases where documented, not permission to substitute a different token type. Prefer Authorization: Bearer to keep credentials out of URLs. 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. SoundSync-wide customer suspension returns 403 CUSTOMER_ACCOUNT_RESTRICTED, including for an existing shared account session; store closure remains store-scoped. Shared library tokens follow their own token/ownership checks and do not replace required customer-account sign-in.",
        "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 session token",
        "x-access-scope": "Current customer-account session and verified customer ownership. Store-scoped sessions remain confined to their storefront; a legacy serial/download token is not account sign-in.",
        "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",
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "CUSTOMER_STORE_CLOSED",
          "CUSTOMER_ACCOUNT_REQUIRED"
        ],
        "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": "Requires a current customer-account session, either shared SoundSync sign-in or an authorized store-scoped customer session. A bare legacy serial/download proof returns 403 CUSTOMER_ACCOUNT_REQUIRED. The query names token, download_token and libraryToken are transport aliases where documented, not permission to substitute a different token type. Prefer Authorization: Bearer to keep credentials out of URLs. 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. SoundSync-wide customer suspension returns 403 CUSTOMER_ACCOUNT_RESTRICTED, including for an existing shared account session; store closure remains store-scoped. Shared library tokens follow their own token/ownership checks and do not replace required customer-account sign-in.",
        "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": "Account Bearer session token",
        "x-access-scope": "Current customer-account session and verified customer ownership. Store-scoped sessions remain confined to their storefront; a legacy serial/download token is not account sign-in.",
        "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": [
          {
            "AccountSession": []
          }
        ],
        "x-contract-coverage": "Reviewed 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",
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "CUSTOMER_STORE_CLOSED",
          "CUSTOMER_ACCOUNT_REQUIRED"
        ],
        "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. SoundSync-wide customer suspension returns 403 CUSTOMER_ACCOUNT_RESTRICTED, including for an existing shared account session; store closure remains store-scoped. Shared library tokens follow their own token/ownership checks and do not replace required customer-account sign-in.",
        "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 session token",
        "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",
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "CUSTOMER_STORE_CLOSED"
        ],
        "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 session token",
        "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/activate": {
      "post": {
        "summary": "POST /api/license/v1/activate",
        "description": "Active compatibility alias of POST /api/license/v1/activate. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. In bounded-grace mode, JUCE requires an authorized signed offline_lease. Protocol 2 permanent-device ownership instead requires the matching SDK to verify explicit signed product_authorization and any required content_authorization; the absence of an offline_lease alone is not a denial in that mode. Protocol 2 adds independently verified product/content authorizations. A pending status or catalog response is not playback permission. Product ownership spans releases; content software compatibility, account/device binding, epochs, signed deadlines and explicit denials remain enforced. permanent_device ownership has no recurring offline deadline only when an authorized signed product/content grant explicitly allows it; ordinary grace and subscription/trial permission remain bounded. A query or body format=hise_text or hise_text selects compact SSACTIVATE text on the successful serial activation branch. Other activation/error branches can still return JSON; format is not a universal content-negotiation guarantee. Default JSON retains the complete response, including any signed offline grant.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/licensing"
        },
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "const": "hise_text"
            },
            "description": "Optional compact HISE transport on successful serial activation or claim-status; default is JSON."
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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."
                    },
                    "product_authorization": {
                      "type": "object",
                      "properties": {
                        "alg": {
                          "const": "RS256"
                        },
                        "kid": {
                          "type": "string"
                        },
                        "payload": {
                          "type": "string"
                        },
                        "signature": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "alg",
                        "kid",
                        "payload",
                        "signature"
                      ]
                    },
                    "content_authorization": {
                      "type": "object",
                      "properties": {
                        "alg": {
                          "const": "RS256"
                        },
                        "kid": {
                          "type": "string"
                        },
                        "payload": {
                          "type": "string"
                        },
                        "signature": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "alg",
                        "kid",
                        "payload",
                        "signature"
                      ]
                    },
                    "unavailable_content": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "contentId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "releaseId": {
                            "type": "string",
                            "format": "uuid"
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "other_major_authorizations": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "host_version": {
                            "type": "string"
                          },
                          "product_authorization": {
                            "type": "object",
                            "properties": {
                              "alg": {
                                "const": "RS256"
                              },
                              "kid": {
                                "type": "string"
                              },
                              "payload": {
                                "type": "string"
                              },
                              "signature": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "required": [
                              "alg",
                              "kid",
                              "payload",
                              "signature"
                            ]
                          },
                          "content_authorization": {
                            "type": "object",
                            "properties": {
                              "alg": {
                                "const": "RS256"
                              },
                              "kid": {
                                "type": "string"
                              },
                              "payload": {
                                "type": "string"
                              },
                              "signature": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "required": [
                              "alg",
                              "kid",
                              "payload",
                              "signature"
                            ]
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "protected_activation_id": {
                      "type": "string"
                    },
                    "protected_authorization_status": {
                      "type": "string",
                      "enum": [
                        "ready",
                        "pending"
                      ]
                    }
                  },
                  "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 authentication.",
            "content": {
              "application/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": "ProductAppId + ProductPluginKey + ProductPluginSecret OR ProductAppId + ProductId + NativePublicClient",
        "x-access-scope": "Product, app, credential, environment, and machine 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": [
          {
            "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",
          "services/protectedContentAuthorizationService.js",
          "services/protectedProductDeviceService.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"
                  },
                  "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"
                  },
                  "content_protocol_version": {
                    "type": "integer",
                    "enum": [
                      1,
                      2
                    ],
                    "description": "Use 2 with the matching maintained native package."
                  },
                  "content_releases": {
                    "type": "array",
                    "maxItems": 64,
                    "items": {
                      "type": "object",
                      "properties": {
                        "contentId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "releaseId": {
                          "type": "string",
                          "format": "uuid"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "contentId",
                        "releaseId"
                      ]
                    }
                  },
                  "previous_content_authorization": {
                    "type": "object",
                    "properties": {
                      "alg": {
                        "const": "RS256"
                      },
                      "kid": {
                        "type": "string"
                      },
                      "payload": {
                        "type": "string"
                      },
                      "signature": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true,
                    "required": [
                      "alg",
                      "kid",
                      "payload",
                      "signature"
                    ]
                  }
                },
                "additionalProperties": true,
                "anyOf": [
                  {
                    "required": [
                      "instance_id"
                    ]
                  },
                  {
                    "required": [
                      "machine_id"
                    ]
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/license/activation/start": {
      "post": {
        "summary": "POST /api/license/v1/activation/start",
        "description": "Active compatibility alias of POST /api/license/v1/activation/start. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/licensing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "ProductAppId + ProductPluginKey + ProductPluginSecret OR ProductAppId + ProductId + NativePublicClient",
        "x-access-scope": "Product, app, credential, environment, and machine 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": [
          {
            "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/activation/verify-email": {
      "post": {
        "summary": "POST /api/license/v1/activation/verify-email",
        "description": "Active compatibility alias of POST /api/license/v1/activation/verify-email. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. Protocol 2 adds independently verified product/content authorizations. A pending status or catalog response is not playback permission. Product ownership spans releases; content software compatibility, account/device binding, epochs, signed deadlines and explicit denials remain enforced. permanent_device ownership has no recurring offline deadline only when an authorized signed product/content grant explicitly allows it; ordinary grace and subscription/trial permission remain bounded.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/licensing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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."
                    },
                    "product_authorization": {
                      "type": "object",
                      "properties": {
                        "alg": {
                          "const": "RS256"
                        },
                        "kid": {
                          "type": "string"
                        },
                        "payload": {
                          "type": "string"
                        },
                        "signature": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "alg",
                        "kid",
                        "payload",
                        "signature"
                      ]
                    },
                    "content_authorization": {
                      "type": "object",
                      "properties": {
                        "alg": {
                          "const": "RS256"
                        },
                        "kid": {
                          "type": "string"
                        },
                        "payload": {
                          "type": "string"
                        },
                        "signature": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "alg",
                        "kid",
                        "payload",
                        "signature"
                      ]
                    },
                    "unavailable_content": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "contentId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "releaseId": {
                            "type": "string",
                            "format": "uuid"
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "other_major_authorizations": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "host_version": {
                            "type": "string"
                          },
                          "product_authorization": {
                            "type": "object",
                            "properties": {
                              "alg": {
                                "const": "RS256"
                              },
                              "kid": {
                                "type": "string"
                              },
                              "payload": {
                                "type": "string"
                              },
                              "signature": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "required": [
                              "alg",
                              "kid",
                              "payload",
                              "signature"
                            ]
                          },
                          "content_authorization": {
                            "type": "object",
                            "properties": {
                              "alg": {
                                "const": "RS256"
                              },
                              "kid": {
                                "type": "string"
                              },
                              "payload": {
                                "type": "string"
                              },
                              "signature": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "required": [
                              "alg",
                              "kid",
                              "payload",
                              "signature"
                            ]
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "protected_activation_id": {
                      "type": "string"
                    },
                    "protected_authorization_status": {
                      "type": "string",
                      "enum": [
                        "ready",
                        "pending"
                      ]
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/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": "ProductAppId + ProductPluginKey + ProductPluginSecret OR ProductAppId + ProductId + NativePublicClient",
        "x-access-scope": "Product, app, credential, environment, and machine 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": [
          {
            "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/protectedContentAuthorizationService.js",
          "services/protectedProductDeviceService.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}$"
                  },
                  "content_protocol_version": {
                    "type": "integer",
                    "enum": [
                      1,
                      2
                    ],
                    "description": "Use 2 with the matching maintained native package."
                  },
                  "content_releases": {
                    "type": "array",
                    "maxItems": 64,
                    "items": {
                      "type": "object",
                      "properties": {
                        "contentId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "releaseId": {
                          "type": "string",
                          "format": "uuid"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "contentId",
                        "releaseId"
                      ]
                    }
                  },
                  "previous_content_authorization": {
                    "type": "object",
                    "properties": {
                      "alg": {
                        "const": "RS256"
                      },
                      "kid": {
                        "type": "string"
                      },
                      "payload": {
                        "type": "string"
                      },
                      "signature": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true,
                    "required": [
                      "alg",
                      "kid",
                      "payload",
                      "signature"
                    ]
                  }
                },
                "required": [
                  "email",
                  "instance_id",
                  "code"
                ],
                "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/claim": {
      "post": {
        "summary": "POST /api/license/v1/claim",
        "description": "Active compatibility alias of POST /api/license/v1/claim. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/licensing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "ProductAppId + ProductPluginKey + ProductPluginSecret OR ProductAppId + ProductId + NativePublicClient",
        "x-access-scope": "Product, app, credential, environment, and machine 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": [
          {
            "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/claim-status": {
      "post": {
        "summary": "POST /api/license/v1/claim-status",
        "description": "Active compatibility alias of POST /api/license/v1/claim-status. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. A query format=hise_text or hise_text selects compact SSCLAIM text for successful claim-status transport. Default JSON preserves the full response; an HTTP 200 identity/pending state is not activation.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/licensing"
        },
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "const": "hise_text"
            },
            "description": "Optional compact HISE transport on successful serial activation or claim-status; default is JSON."
          }
        ],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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
                }
              },
              "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 authentication.",
            "content": {
              "application/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": "ProductAppId + ProductPluginKey + ProductPluginSecret OR ProductAppId + ProductId + NativePublicClient",
        "x-access-scope": "Product, app, credential, environment, and machine 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": [
          {
            "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/deactivate": {
      "post": {
        "summary": "POST /api/license/v1/deactivate",
        "description": "Active compatibility alias of POST /api/license/v1/deactivate. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/licensing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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": "ProductAppId + ProductPluginKey + ProductPluginSecret OR ProductAppId + ProductId + NativePublicClient",
        "x-access-scope": "Product, app, credential, environment, and machine 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": [
          {
            "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/ping": {
      "get": {
        "summary": "Inspect parsed app identity and key length without authenticating",
        "description": "Returns ok:true with parsed saw.appId (default soundsync) and saw.appKey_len. It does not validate the key, record plugin verification, activate a machine, issue a grant or establish current licensing health. Do not send real secrets just to test reachability; an empty-key response is expected without credentials.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/licensing"
        },
        "parameters": [
          {
            "name": "x-ss-app-id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: ok, saw.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "saw": {
                      "type": "object",
                      "properties": {
                        "appId": {
                          "type": "string"
                        },
                        "appKey_len": {
                          "type": "integer"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "appId",
                        "appKey_len"
                      ]
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "ok",
                    "saw"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific 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 diagnostic parsing only; no product credential or customer authorization is verified.",
        "x-request-fields": [
          "header x-ss-app-id: 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/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. In bounded-grace mode, JUCE requires an authorized signed offline_lease. Protocol 2 permanent-device ownership instead requires the matching SDK to verify explicit signed product_authorization and any required content_authorization; the absence of an offline_lease alone is not a denial in that mode. Protocol 2 adds independently verified product/content authorizations. A pending status or catalog response is not playback permission. Product ownership spans releases; content software compatibility, account/device binding, epochs, signed deadlines and explicit denials remain enforced. permanent_device ownership has no recurring offline deadline only when an authorized signed product/content grant explicitly allows it; ordinary grace and subscription/trial permission remain bounded. A query or body format=hise_text or hise_text selects compact SSACTIVATE text on the successful serial activation branch. Other activation/error branches can still return JSON; format is not a universal content-negotiation guarantee. Default JSON retains the complete response, including any signed offline grant. 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": [
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "const": "hise_text"
            },
            "description": "Optional compact HISE transport on successful serial activation or claim-status; default is JSON."
          }
        ],
        "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."
                    },
                    "product_authorization": {
                      "type": "object",
                      "properties": {
                        "alg": {
                          "const": "RS256"
                        },
                        "kid": {
                          "type": "string"
                        },
                        "payload": {
                          "type": "string"
                        },
                        "signature": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "alg",
                        "kid",
                        "payload",
                        "signature"
                      ]
                    },
                    "content_authorization": {
                      "type": "object",
                      "properties": {
                        "alg": {
                          "const": "RS256"
                        },
                        "kid": {
                          "type": "string"
                        },
                        "payload": {
                          "type": "string"
                        },
                        "signature": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "alg",
                        "kid",
                        "payload",
                        "signature"
                      ]
                    },
                    "unavailable_content": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "contentId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "releaseId": {
                            "type": "string",
                            "format": "uuid"
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "other_major_authorizations": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "host_version": {
                            "type": "string"
                          },
                          "product_authorization": {
                            "type": "object",
                            "properties": {
                              "alg": {
                                "const": "RS256"
                              },
                              "kid": {
                                "type": "string"
                              },
                              "payload": {
                                "type": "string"
                              },
                              "signature": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "required": [
                              "alg",
                              "kid",
                              "payload",
                              "signature"
                            ]
                          },
                          "content_authorization": {
                            "type": "object",
                            "properties": {
                              "alg": {
                                "const": "RS256"
                              },
                              "kid": {
                                "type": "string"
                              },
                              "payload": {
                                "type": "string"
                              },
                              "signature": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "required": [
                              "alg",
                              "kid",
                              "payload",
                              "signature"
                            ]
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "protected_activation_id": {
                      "type": "string"
                    },
                    "protected_authorization_status": {
                      "type": "string",
                      "enum": [
                        "ready",
                        "pending"
                      ]
                    }
                  },
                  "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 authentication.",
            "content": {
              "application/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": [
          "query format: value. Optional compact HISE transport on successful serial activation or claim-status; default is JSON.",
          "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",
          "content_protocol_version: 1 | 2. Use 2 with the matching maintained native package.",
          "content_releases: array",
          "previous_content_authorization: object"
        ],
        "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",
          "services/protectedContentAuthorizationService.js",
          "services/protectedProductDeviceService.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"
                  },
                  "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"
                  },
                  "content_protocol_version": {
                    "type": "integer",
                    "enum": [
                      1,
                      2
                    ],
                    "description": "Use 2 with the matching maintained native package."
                  },
                  "content_releases": {
                    "type": "array",
                    "maxItems": 64,
                    "items": {
                      "type": "object",
                      "properties": {
                        "contentId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "releaseId": {
                          "type": "string",
                          "format": "uuid"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "contentId",
                        "releaseId"
                      ]
                    }
                  },
                  "previous_content_authorization": {
                    "type": "object",
                    "properties": {
                      "alg": {
                        "const": "RS256"
                      },
                      "kid": {
                        "type": "string"
                      },
                      "payload": {
                        "type": "string"
                      },
                      "signature": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true,
                    "required": [
                      "alg",
                      "kid",
                      "payload",
                      "signature"
                    ]
                  }
                },
                "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, app, credential, environment, and machine scoped.",
        "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. Protocol 2 adds independently verified product/content authorizations. A pending status or catalog response is not playback permission. Product ownership spans releases; content software compatibility, account/device binding, epochs, signed deadlines and explicit denials remain enforced. permanent_device ownership has no recurring offline deadline only when an authorized signed product/content grant explicitly allows it; ordinary grace and subscription/trial permission remain bounded.",
        "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."
                    },
                    "product_authorization": {
                      "type": "object",
                      "properties": {
                        "alg": {
                          "const": "RS256"
                        },
                        "kid": {
                          "type": "string"
                        },
                        "payload": {
                          "type": "string"
                        },
                        "signature": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "alg",
                        "kid",
                        "payload",
                        "signature"
                      ]
                    },
                    "content_authorization": {
                      "type": "object",
                      "properties": {
                        "alg": {
                          "const": "RS256"
                        },
                        "kid": {
                          "type": "string"
                        },
                        "payload": {
                          "type": "string"
                        },
                        "signature": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "alg",
                        "kid",
                        "payload",
                        "signature"
                      ]
                    },
                    "unavailable_content": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "contentId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "releaseId": {
                            "type": "string",
                            "format": "uuid"
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "other_major_authorizations": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "host_version": {
                            "type": "string"
                          },
                          "product_authorization": {
                            "type": "object",
                            "properties": {
                              "alg": {
                                "const": "RS256"
                              },
                              "kid": {
                                "type": "string"
                              },
                              "payload": {
                                "type": "string"
                              },
                              "signature": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "required": [
                              "alg",
                              "kid",
                              "payload",
                              "signature"
                            ]
                          },
                          "content_authorization": {
                            "type": "object",
                            "properties": {
                              "alg": {
                                "const": "RS256"
                              },
                              "kid": {
                                "type": "string"
                              },
                              "payload": {
                                "type": "string"
                              },
                              "signature": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "required": [
                              "alg",
                              "kid",
                              "payload",
                              "signature"
                            ]
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "protected_activation_id": {
                      "type": "string"
                    },
                    "protected_authorization_status": {
                      "type": "string",
                      "enum": [
                        "ready",
                        "pending"
                      ]
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/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, app, credential, environment, and machine scoped.",
        "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)",
          "content_protocol_version: 1 | 2. Use 2 with the matching maintained native package.",
          "content_releases: array",
          "previous_content_authorization: object"
        ],
        "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/protectedContentAuthorizationService.js",
          "services/protectedProductDeviceService.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}$"
                  },
                  "content_protocol_version": {
                    "type": "integer",
                    "enum": [
                      1,
                      2
                    ],
                    "description": "Use 2 with the matching maintained native package."
                  },
                  "content_releases": {
                    "type": "array",
                    "maxItems": 64,
                    "items": {
                      "type": "object",
                      "properties": {
                        "contentId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "releaseId": {
                          "type": "string",
                          "format": "uuid"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "contentId",
                        "releaseId"
                      ]
                    }
                  },
                  "previous_content_authorization": {
                    "type": "object",
                    "properties": {
                      "alg": {
                        "const": "RS256"
                      },
                      "kid": {
                        "type": "string"
                      },
                      "payload": {
                        "type": "string"
                      },
                      "signature": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true,
                    "required": [
                      "alg",
                      "kid",
                      "payload",
                      "signature"
                    ]
                  }
                },
                "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. A query format=hise_text or hise_text selects compact SSCLAIM text for successful claim-status transport. Default JSON preserves the full response; an HTTP 200 identity/pending state is not activation. 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"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "const": "hise_text"
            },
            "description": "Optional compact HISE transport on successful serial activation or claim-status; default is JSON."
          }
        ],
        "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
                }
              },
              "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 authentication.",
            "content": {
              "application/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",
          "query format: value. Optional compact HISE transport on successful serial activation or claim-status; default is JSON."
        ],
        "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. A query format=hise_text or hise_text selects compact SSCLAIM text for successful claim-status transport. Default JSON preserves the full response; an HTTP 200 identity/pending state is not activation. 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": "format",
            "in": "query",
            "required": false,
            "schema": {
              "const": "hise_text"
            },
            "description": "Optional compact HISE transport on successful serial activation or claim-status; default is JSON."
          }
        ],
        "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
                }
              },
              "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 authentication.",
            "content": {
              "application/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 format: value. Optional compact HISE transport on successful serial activation or claim-status; default is JSON.",
          "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.9.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. Protocol 2 adds independently verified product/content authorizations. A pending status or catalog response is not playback permission. Product ownership spans releases; content software compatibility, account/device binding, epochs, signed deadlines and explicit denials remain enforced. permanent_device ownership has no recurring offline deadline only when an authorized signed product/content grant explicitly allows it; ordinary grace and subscription/trial permission remain bounded. 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. SoundSync-wide customer suspension returns 403 CUSTOMER_ACCOUNT_RESTRICTED, including for an existing shared account session; store closure remains store-scoped. Shared library tokens follow their own token/ownership checks and do not replace required customer-account sign-in.",
        "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."
                    },
                    "product_authorization": {
                      "type": "object",
                      "properties": {
                        "alg": {
                          "const": "RS256"
                        },
                        "kid": {
                          "type": "string"
                        },
                        "payload": {
                          "type": "string"
                        },
                        "signature": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "alg",
                        "kid",
                        "payload",
                        "signature"
                      ]
                    },
                    "content_authorization": {
                      "type": "object",
                      "properties": {
                        "alg": {
                          "const": "RS256"
                        },
                        "kid": {
                          "type": "string"
                        },
                        "payload": {
                          "type": "string"
                        },
                        "signature": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "alg",
                        "kid",
                        "payload",
                        "signature"
                      ]
                    },
                    "unavailable_content": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "contentId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "releaseId": {
                            "type": "string",
                            "format": "uuid"
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "other_major_authorizations": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "host_version": {
                            "type": "string"
                          },
                          "product_authorization": {
                            "type": "object",
                            "properties": {
                              "alg": {
                                "const": "RS256"
                              },
                              "kid": {
                                "type": "string"
                              },
                              "payload": {
                                "type": "string"
                              },
                              "signature": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "required": [
                              "alg",
                              "kid",
                              "payload",
                              "signature"
                            ]
                          },
                          "content_authorization": {
                            "type": "object",
                            "properties": {
                              "alg": {
                                "const": "RS256"
                              },
                              "kid": {
                                "type": "string"
                              },
                              "payload": {
                                "type": "string"
                              },
                              "signature": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "required": [
                              "alg",
                              "kid",
                              "payload",
                              "signature"
                            ]
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "protected_activation_id": {
                      "type": "string"
                    },
                    "protected_authorization_status": {
                      "type": "string",
                      "enum": [
                        "ready",
                        "pending"
                      ]
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/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",
          "content_protocol_version: 1 | 2. Use 2 with the matching maintained native package.",
          "content_releases: array",
          "previous_content_authorization: object"
        ],
        "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",
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "CUSTOMER_STORE_CLOSED"
        ],
        "x-source-files": [
          "routes/licenseRoutes.js",
          "controllers/licenseController.js",
          "middleware/authMiddleware.js",
          "services/protectedContentAuthorizationService.js",
          "services/protectedProductDeviceService.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
                  },
                  "content_protocol_version": {
                    "type": "integer",
                    "enum": [
                      1,
                      2
                    ],
                    "description": "Use 2 with the matching maintained native package."
                  },
                  "content_releases": {
                    "type": "array",
                    "maxItems": 64,
                    "items": {
                      "type": "object",
                      "properties": {
                        "contentId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "releaseId": {
                          "type": "string",
                          "format": "uuid"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "contentId",
                        "releaseId"
                      ]
                    }
                  },
                  "previous_content_authorization": {
                    "type": "object",
                    "properties": {
                      "alg": {
                        "const": "RS256"
                      },
                      "kid": {
                        "type": "string"
                      },
                      "payload": {
                        "type": "string"
                      },
                      "signature": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true,
                    "required": [
                      "alg",
                      "kid",
                      "payload",
                      "signature"
                    ]
                  }
                },
                "additionalProperties": true,
                "allOf": [
                  {
                    "anyOf": [
                      {
                        "required": [
                          "instance_id"
                        ]
                      },
                      {
                        "required": [
                          "machine_id"
                        ]
                      }
                    ]
                  },
                  {
                    "anyOf": [
                      {
                        "required": [
                          "email",
                          "password"
                        ]
                      },
                      {
                        "required": [
                          "customer_token"
                        ]
                      }
                    ]
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/license/v1/deactivate": {
      "post": {
        "summary": "Deactivate the authenticated server-side machine activation.",
        "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: Confirmed success deactivates the authorized server activation and records its event. The HTTP endpoint does not lock local audio by itself. Clear obsolete activation and grace state only after confirmed server deactivation; retain pending proof and the local block until then. Let the maintained JUCE runtime manage its protected 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/protected-content": {
      "post": {
        "summary": "Read a protected catalog or request one release using activated native proof",
        "description": "Send instance_id. For device-credential authorization also send numeric content_protocol_version:2 (1 remains supported); device_credential alone does not select that branch. A valid plugin_session_id is the alternative activated proof. Send the real plugin_version or host_version; a host_version query fallback is supported. Omit release_id to list compatible releases; supply it for a private download. This catalog call is not activation and does not grant playback. SoundSync-wide customer suspension blocks new catalogs and download links. Store-only restrictions remain scoped to that store; product ownership is rechecked. Unavailable account verification fails closed with 503 SESSION_VERIFICATION_UNAVAILABLE. These online checks do not rewrite issued offline grants or change Access grace.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/protected-content"
        },
        "parameters": [
          {
            "name": "host_version",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Supported fallback when plugin_version and host_version are absent from JSON."
          },
          {
            "name": "release_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Supported fallback when release_id is absent from JSON."
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: review the response schema below.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "releases": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "contentId": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "releaseId": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "productId": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "name": {
                                "type": "string"
                              },
                              "revision": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "owned": {
                                "type": "boolean"
                              },
                              "included": {
                                "type": "boolean"
                              },
                              "available": {
                                "type": "boolean"
                              },
                              "requiresParent": {
                                "type": "boolean"
                              },
                              "packageHash": {
                                "type": "string"
                              },
                              "manifest": {
                                "type": "object",
                                "properties": {
                                  "alg": {
                                    "const": "RS256"
                                  },
                                  "kid": {
                                    "type": "string"
                                  },
                                  "payload": {
                                    "type": "string"
                                  },
                                  "signature": {
                                    "type": "string"
                                  }
                                },
                                "additionalProperties": true,
                                "required": [
                                  "alg",
                                  "kid",
                                  "payload",
                                  "signature"
                                ]
                              },
                              "downloadPath": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              }
                            },
                            "additionalProperties": true
                          }
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "releases"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string"
                        },
                        "filename": {
                          "type": "string"
                        },
                        "expiresIn": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "contentId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "releaseId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "packageHash": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "url",
                        "filename",
                        "expiresIn",
                        "contentId",
                        "releaseId",
                        "packageHash"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific 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": "Matching generated product identity plus a valid activated native device/session proof; no caller-selected customer authority.",
        "x-request-fields": [
          "query host_version: string. Supported fallback when plugin_version and host_version are absent from JSON.",
          "query release_id: string. Supported fallback when release_id is absent from JSON.",
          "product_id: integer",
          "instance_id: string (required)",
          "device_credential: string",
          "content_protocol_version: 1 | 2",
          "plugin_session_id: string",
          "plugin_version: string",
          "host_version: string",
          "release_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": [
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "SESSION_VERIFICATION_UNAVAILABLE",
          "LIBRARY_USER_NOT_FOUND",
          "library_customer_unavailable",
          "CUSTOMER_STORE_CLOSED"
        ],
        "x-source-files": [
          "routes/licenseRoutes.js",
          "controllers/licenseController.js",
          "services/protectedContentCatalogService.js",
          "services/customerAccountRestrictionService.js",
          "services/customerStoreAccessService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "product_id": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "instance_id": {
                    "type": "string",
                    "minLength": 1
                  },
                  "device_credential": {
                    "type": "string",
                    "minLength": 1
                  },
                  "content_protocol_version": {
                    "type": "integer",
                    "enum": [
                      1,
                      2
                    ]
                  },
                  "plugin_session_id": {
                    "type": "string",
                    "minLength": 1
                  },
                  "plugin_version": {
                    "type": "string",
                    "minLength": 1
                  },
                  "host_version": {
                    "type": "string",
                    "minLength": 1
                  },
                  "release_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "instance_id"
                ],
                "anyOf": [
                  {
                    "required": [
                      "device_credential",
                      "content_protocol_version"
                    ]
                  },
                  {
                    "required": [
                      "plugin_session_id"
                    ]
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/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. In bounded-grace mode, JUCE requires an authorized signed offline_lease. Protocol 2 permanent-device ownership instead requires the matching SDK to verify explicit signed product_authorization and any required content_authorization; the absence of an offline_lease alone is not a denial in that mode. Protocol 2 adds independently verified product/content authorizations. A pending status or catalog response is not playback permission. Product ownership spans releases; content software compatibility, account/device binding, epochs, signed deadlines and explicit denials remain enforced. permanent_device ownership has no recurring offline deadline only when an authorized signed product/content grant explicitly allows it; ordinary grace and subscription/trial permission remain bounded. 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."
                    },
                    "product_authorization": {
                      "type": "object",
                      "properties": {
                        "alg": {
                          "const": "RS256"
                        },
                        "kid": {
                          "type": "string"
                        },
                        "payload": {
                          "type": "string"
                        },
                        "signature": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "alg",
                        "kid",
                        "payload",
                        "signature"
                      ]
                    },
                    "content_authorization": {
                      "type": "object",
                      "properties": {
                        "alg": {
                          "const": "RS256"
                        },
                        "kid": {
                          "type": "string"
                        },
                        "payload": {
                          "type": "string"
                        },
                        "signature": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "alg",
                        "kid",
                        "payload",
                        "signature"
                      ]
                    },
                    "unavailable_content": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "contentId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "releaseId": {
                            "type": "string",
                            "format": "uuid"
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "other_major_authorizations": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "host_version": {
                            "type": "string"
                          },
                          "product_authorization": {
                            "type": "object",
                            "properties": {
                              "alg": {
                                "const": "RS256"
                              },
                              "kid": {
                                "type": "string"
                              },
                              "payload": {
                                "type": "string"
                              },
                              "signature": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "required": [
                              "alg",
                              "kid",
                              "payload",
                              "signature"
                            ]
                          },
                          "content_authorization": {
                            "type": "object",
                            "properties": {
                              "alg": {
                                "const": "RS256"
                              },
                              "kid": {
                                "type": "string"
                              },
                              "payload": {
                                "type": "string"
                              },
                              "signature": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "required": [
                              "alg",
                              "kid",
                              "payload",
                              "signature"
                            ]
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "protected_activation_id": {
                      "type": "string"
                    },
                    "protected_authorization_status": {
                      "type": "string",
                      "enum": [
                        "ready",
                        "pending"
                      ]
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/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",
          "content_protocol_version: 1 | 2. Use 2 with the matching maintained native package.",
          "content_releases: array",
          "previous_content_authorization: object"
        ],
        "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",
          "services/protectedContentAuthorizationService.js",
          "services/protectedProductDeviceService.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"
                  },
                  "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"
                  },
                  "content_protocol_version": {
                    "type": "integer",
                    "enum": [
                      1,
                      2
                    ],
                    "description": "Use 2 with the matching maintained native package."
                  },
                  "content_releases": {
                    "type": "array",
                    "maxItems": 64,
                    "items": {
                      "type": "object",
                      "properties": {
                        "contentId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "releaseId": {
                          "type": "string",
                          "format": "uuid"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "contentId",
                        "releaseId"
                      ]
                    }
                  },
                  "previous_content_authorization": {
                    "type": "object",
                    "properties": {
                      "alg": {
                        "const": "RS256"
                      },
                      "kid": {
                        "type": "string"
                      },
                      "payload": {
                        "type": "string"
                      },
                      "signature": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true,
                    "required": [
                      "alg",
                      "kid",
                      "payload",
                      "signature"
                    ]
                  }
                },
                "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/license/validate": {
      "post": {
        "summary": "POST /api/license/v1/validate",
        "description": "Active compatibility alias of POST /api/license/v1/validate. The same handler, authorization, state checks and side effects apply. An alias is not a dry run or a fresh idempotency boundary. 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. In bounded-grace mode, JUCE requires an authorized signed offline_lease. Protocol 2 permanent-device ownership instead requires the matching SDK to verify explicit signed product_authorization and any required content_authorization; the absence of an offline_lease alone is not a denial in that mode. Protocol 2 adds independently verified product/content authorizations. A pending status or catalog response is not playback permission. Product ownership spans releases; content software compatibility, account/device binding, epochs, signed deadlines and explicit denials remain enforced. permanent_device ownership has no recurring offline deadline only when an authorized signed product/content grant explicitly allows it; ordinary grace and subscription/trial permission remain bounded.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/licensing"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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."
                    },
                    "product_authorization": {
                      "type": "object",
                      "properties": {
                        "alg": {
                          "const": "RS256"
                        },
                        "kid": {
                          "type": "string"
                        },
                        "payload": {
                          "type": "string"
                        },
                        "signature": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "alg",
                        "kid",
                        "payload",
                        "signature"
                      ]
                    },
                    "content_authorization": {
                      "type": "object",
                      "properties": {
                        "alg": {
                          "const": "RS256"
                        },
                        "kid": {
                          "type": "string"
                        },
                        "payload": {
                          "type": "string"
                        },
                        "signature": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "alg",
                        "kid",
                        "payload",
                        "signature"
                      ]
                    },
                    "unavailable_content": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "contentId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "releaseId": {
                            "type": "string",
                            "format": "uuid"
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "other_major_authorizations": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "host_version": {
                            "type": "string"
                          },
                          "product_authorization": {
                            "type": "object",
                            "properties": {
                              "alg": {
                                "const": "RS256"
                              },
                              "kid": {
                                "type": "string"
                              },
                              "payload": {
                                "type": "string"
                              },
                              "signature": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "required": [
                              "alg",
                              "kid",
                              "payload",
                              "signature"
                            ]
                          },
                          "content_authorization": {
                            "type": "object",
                            "properties": {
                              "alg": {
                                "const": "RS256"
                              },
                              "kid": {
                                "type": "string"
                              },
                              "payload": {
                                "type": "string"
                              },
                              "signature": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "required": [
                              "alg",
                              "kid",
                              "payload",
                              "signature"
                            ]
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "protected_activation_id": {
                      "type": "string"
                    },
                    "protected_authorization_status": {
                      "type": "string",
                      "enum": [
                        "ready",
                        "pending"
                      ]
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/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": "ProductAppId + ProductPluginKey + ProductPluginSecret OR ProductAppId + ProductId + NativePublicClient",
        "x-access-scope": "Product, app, credential, environment, and machine 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": [
          {
            "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",
          "services/protectedContentAuthorizationService.js",
          "services/protectedProductDeviceService.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"
                  },
                  "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"
                  },
                  "content_protocol_version": {
                    "type": "integer",
                    "enum": [
                      1,
                      2
                    ],
                    "description": "Use 2 with the matching maintained native package."
                  },
                  "content_releases": {
                    "type": "array",
                    "maxItems": 64,
                    "items": {
                      "type": "object",
                      "properties": {
                        "contentId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "releaseId": {
                          "type": "string",
                          "format": "uuid"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "contentId",
                        "releaseId"
                      ]
                    }
                  },
                  "previous_content_authorization": {
                    "type": "object",
                    "properties": {
                      "alg": {
                        "const": "RS256"
                      },
                      "kid": {
                        "type": "string"
                      },
                      "payload": {
                        "type": "string"
                      },
                      "signature": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true,
                    "required": [
                      "alg",
                      "kid",
                      "payload",
                      "signature"
                    ]
                  }
                },
                "additionalProperties": true,
                "anyOf": [
                  {
                    "required": [
                      "instance_id"
                    ]
                  },
                  {
                    "required": [
                      "machine_id"
                    ]
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/license/verify-license": {
      "get": {
        "summary": "Consume an emailed serial-claim token and return HTML",
        "description": "Consumes the serial-claim verification token and returns an HTML result, not JSON or a plugin validation token. The root /verify-license browser link calls the same handler. Missing/invalid tokens return 400 HTML; expired tokens return 410 HTML. This GET can confirm a claim and is not a read-only health probe. Return to the plugin, check claim-status and perform the separate final activation on the same product and machine. Email verification alone does not grant offline access.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/licensing"
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Private serial-claim email token; never log or share the URL."
          }
        ],
        "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"
                }
              }
            }
          },
          "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 emailed private verification token authorizes claim confirmation; this is not an account Bearer session or activation proof.",
        "x-request-fields": [
          "query token: string (required). Private serial-claim email token; never log or share the URL."
        ],
        "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/licenseRoutes.js",
          "controllers/licenseController.js",
          "services/licenseSerialClaimService.js"
        ]
      }
    },
    "/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 session token",
        "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 session token",
        "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/meta-capi/config": {
      "post": {
        "summary": "Resolve whether measurement is available on this public surface",
        "description": "Scope/configuration failures return available:false. Availability is not visitor permission, provider acceptance or a guarantee that an event will be forwarded.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/meta-capi"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: available, developerId.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "available": {
                      "type": "boolean"
                    },
                    "developerId": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "minimum": 1
                        },
                        {
                          "type": "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 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": "Request Origin must match the validated published/verified public URL and developer surface.",
        "x-request-fields": [
          "url: string (required)",
          "storefrontSlug: string",
          "productId: integer",
          "bundleId: 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/developerMetaCapiRoutes.js",
          "routes/metaCapiRoutes.js",
          "services/developerMetaCapiService.js",
          "services/metaCapiDeliveryService.js",
          "services/metaCapiPayload.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string"
                  },
                  "storefrontSlug": {
                    "type": "string"
                  },
                  "productId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "bundleId": {
                    "type": "integer",
                    "minimum": 1
                  }
                },
                "additionalProperties": true,
                "required": [
                  "url"
                ]
              }
            }
          }
        }
      }
    },
    "/api/meta-capi/events": {
      "post": {
        "summary": "Submit eligible public measurement without blocking storefront use",
        "description": "Maps supported page/product/cart activity to PageView/ViewContent/AddToCart. 202 ok:true deliberately does not disclose whether an event was retained or sent. Purchase capture is authoritative server checkout accounting, not a caller-supplied Purchase event. Email marketing enrollment is not advertising consent.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/meta-capi"
        },
        "parameters": [],
        "responses": {
          "202": {
            "description": "HTTP 202: ok.",
            "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 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": "Validated developer surface, explicit advertising-measurement consent, matching destination, visitor ID and no GPC/DNT/suppression.",
        "x-request-fields": [
          "url: string (required)",
          "storefrontSlug: string",
          "productId: integer",
          "bundleId: integer",
          "eventType: string (required)",
          "metadata: object",
          "adMeasurement: object (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/developerMetaCapiRoutes.js",
          "routes/metaCapiRoutes.js",
          "services/developerMetaCapiService.js",
          "services/metaCapiDeliveryService.js",
          "services/metaCapiPayload.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string"
                  },
                  "storefrontSlug": {
                    "type": "string"
                  },
                  "productId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "bundleId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "eventType": {
                    "type": "string"
                  },
                  "metadata": {
                    "type": "object",
                    "properties": {
                      "action": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true
                  },
                  "adMeasurement": {
                    "type": "object",
                    "properties": {
                      "developerId": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "visitorId": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "eventId": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "consent": {
                        "type": "boolean"
                      },
                      "fbp": {
                        "type": "string"
                      },
                      "fbc": {
                        "type": "string"
                      },
                      "fbclid": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true
                  }
                },
                "additionalProperties": true,
                "required": [
                  "url",
                  "eventType",
                  "adMeasurement"
                ]
              }
            }
          }
        }
      }
    },
    "/api/meta-capi/privacy": {
      "post": {
        "summary": "Suppress the relevant visitor measurement and cancel pending work",
        "description": "Records the scoped measurement suppression when the surface resolves. Does not control GA4 or email lists. An unresolved surface can return ok:true without a suppression; a storage failure returns 503 and should be retried.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/meta-capi"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: ok.",
            "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 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": "Validated public origin/developer surface and visitor identifier; cannot opt another developer into forwarding.",
        "x-request-fields": [
          "url: string (required)",
          "storefrontSlug: string",
          "productId: integer",
          "bundleId: integer",
          "visitorId: 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/developerMetaCapiRoutes.js",
          "routes/metaCapiRoutes.js",
          "services/developerMetaCapiService.js",
          "services/metaCapiDeliveryService.js",
          "services/metaCapiPayload.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string"
                  },
                  "storefrontSlug": {
                    "type": "string"
                  },
                  "productId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "bundleId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "visitorId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "url",
                  "visitorId"
                ]
              }
            }
          }
        }
      }
    },
    "/api/notices/authorize": {
      "post": {
        "summary": "Authorize notices using a verified shared customer account session",
        "description": "Client customer IDs and email do not establish ownership. The account session and product association are rechecked on private notice requests. This does not create an entitlement.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: token, expiresAt, private, productId, recipientKey.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "private": {
                      "type": "boolean"
                    },
                    "productId": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "recipientKey": {
                      "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 session token",
        "x-access-scope": "Live shared customer account session and an explicit account-linked product/serial relationship. Store-only credentials are not shared account authority.",
        "x-request-fields": [
          "productId: 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-error-codes": [
          "notice_auth_required",
          "notice_auth_expired",
          "notice_auth_revoked",
          "notice_product_mismatch",
          "delivery_instance_mismatch",
          "notice_no_longer_available",
          "notices_disabled"
        ],
        "x-source-files": [
          "routes/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "productId": {
                    "type": "integer",
                    "minimum": 1
                  }
                },
                "additionalProperties": true,
                "required": [
                  "productId"
                ]
              }
            }
          }
        }
      }
    },
    "/api/notices/deliveries/{id}/content": {
      "post": {
        "summary": "Read import instructions or request an authorized content download",
        "description": "Details may omit url/sizeBytes/expiresIn. Download mode needs the download action, actual display, a current lease, managed file and current content ownership. Private signed URLs expire; never publish or retain them as permanent links. A notice does not grant paid content. The native companion saves the file, verifies length/available checksum and shows one platform instruction set. It never installs, extracts, imports or executes it.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: resourceId, name, version, filename, sha256, instructions, supportUrl, url, sizeBytes, expiresIn.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resourceId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "name": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    },
                    "filename": {
                      "type": "string"
                    },
                    "sha256": {
                      "type": "string"
                    },
                    "instructions": {
                      "type": "object",
                      "properties": {
                        "common": {
                          "type": "string"
                        },
                        "windows": {
                          "type": "string"
                        },
                        "mac": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    },
                    "supportUrl": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    },
                    "sizeBytes": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "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"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/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": "Notice-only Bearer capability",
        "x-access-scope": "Notice-only bearer capability, matching product, recipient and editor instance; current campaign eligibility is rechecked.",
        "x-request-fields": [
          "instanceId: string (required)",
          "actionId: string (required)",
          "operation: details | download"
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.",
        "security": [
          {
            "NoticeToken": []
          }
        ],
        "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.",
        "x-error-codes": [
          "notice_auth_required",
          "notice_auth_expired",
          "notice_auth_revoked",
          "notice_product_mismatch",
          "delivery_instance_mismatch",
          "notice_no_longer_available",
          "notices_disabled"
        ],
        "x-source-files": [
          "routes/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js",
          "services/pluginNoticeContentService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instanceId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "actionId": {
                    "type": "string"
                  },
                  "operation": {
                    "type": "string",
                    "enum": [
                      "details",
                      "download"
                    ]
                  }
                },
                "additionalProperties": true,
                "required": [
                  "instanceId",
                  "actionId"
                ]
              }
            }
          }
        }
      }
    },
    "/api/notices/deliveries/{id}/current": {
      "post": {
        "summary": "Recheck eligibility and optionally renew this editor lease",
        "description": "A valid lease can be renewed with keepAlive:true. This records no display. Remove a revoked/expired notice; an offline partition cannot instantly retract already displayed pixels.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: valid, validUntil.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "valid": {
                      "type": "boolean"
                    },
                    "validUntil": {
                      "type": "string",
                      "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"
                }
              }
            }
          },
          "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": "Notice-only Bearer capability",
        "x-access-scope": "Notice-only bearer capability, matching product, recipient and editor instance; current campaign eligibility is rechecked.",
        "x-request-fields": [
          "instanceId: string (required)",
          "keepAlive: boolean"
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.",
        "security": [
          {
            "NoticeToken": []
          }
        ],
        "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.",
        "x-error-codes": [
          "notice_auth_required",
          "notice_auth_expired",
          "notice_auth_revoked",
          "notice_product_mismatch",
          "delivery_instance_mismatch",
          "notice_no_longer_available",
          "notices_disabled"
        ],
        "x-source-files": [
          "routes/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instanceId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "keepAlive": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "instanceId"
                ]
              }
            }
          }
        }
      }
    },
    "/api/notices/deliveries/{id}/receipts": {
      "post": {
        "summary": "Record actual display, dismissal or action outcome",
        "description": "shown follows actual card paint, not fetch/badge arrival. Click/dismiss requires display; action outcomes require a click. Dismiss suppresses this campaign for the recipient across selected products and later versions. A new campaign is independent. Inspect accepted:false rather than treating HTTP 200 as a recorded receipt.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: accepted, duplicate, reason.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accepted": {
                      "type": "boolean"
                    },
                    "duplicate": {
                      "type": "boolean"
                    },
                    "reason": {
                      "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": "Notice-only Bearer capability",
        "x-access-scope": "Notice-only bearer capability, matching product, recipient and editor instance; current campaign eligibility is rechecked.",
        "x-request-fields": [
          "instanceId: string (required)",
          "kind: shown | clicked | dismissed | failed | action_succeeded | action_failed (required)",
          "actionId: string"
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.",
        "security": [
          {
            "NoticeToken": []
          }
        ],
        "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.",
        "x-error-codes": [
          "notice_auth_required",
          "notice_auth_expired",
          "notice_auth_revoked",
          "notice_product_mismatch",
          "delivery_instance_mismatch",
          "notice_no_longer_available",
          "notices_disabled"
        ],
        "x-source-files": [
          "routes/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instanceId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "shown",
                      "clicked",
                      "dismissed",
                      "failed",
                      "action_succeeded",
                      "action_failed"
                    ]
                  },
                  "actionId": {
                    "type": "string"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "instanceId",
                  "kind"
                ]
              }
            }
          }
        }
      }
    },
    "/api/notices/deliveries/{id}/release": {
      "post": {
        "summary": "Release editor-instance ownership without dismissing a campaign",
        "description": "Best-effort release on editor destruction; another eligible instance can reclaim after release or lease expiry.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: released.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "released": {
                      "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"
                }
              }
            }
          },
          "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": "Notice-only Bearer capability",
        "x-access-scope": "Notice-only bearer capability, matching product, recipient and editor instance; current campaign eligibility is rechecked.",
        "x-request-fields": [
          "instanceId: string (required)"
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.",
        "security": [
          {
            "NoticeToken": []
          }
        ],
        "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.",
        "x-error-codes": [
          "notice_auth_required",
          "notice_auth_expired",
          "notice_auth_revoked",
          "notice_product_mismatch",
          "delivery_instance_mismatch",
          "notice_no_longer_available",
          "notices_disabled"
        ],
        "x-source-files": [
          "routes/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instanceId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "instanceId"
                ]
              }
            }
          }
        }
      }
    },
    "/api/notices/events": {
      "post": {
        "summary": "Record a permitted editor event and evaluate notice eligibility",
        "description": "Use a fresh semantic event UUID; retry it with the same ID. Events must be within five minutes of server time. A named control must be registered and cannot be a licensing/password/payment control. Eligibility is not actual display. Limits are 30 events per minute per product/recipient and 120 new sessions per minute per product.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: eligible, duplicate.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "eligible": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "duplicate": {
                      "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"
                }
              }
            }
          },
          "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": "Notice-only Bearer capability",
        "x-access-scope": "Notice-only bearer capability, matching product, recipient and editor instance; current campaign eligibility is rechecked.",
        "x-request-fields": [
          "id: string (required)",
          "sessionId: string (required)",
          "kind: editor_opened | editor_available | control_clicked (required)",
          "occurredAt: string (required)",
          "controlId: string",
          "productId: integer"
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.",
        "security": [
          {
            "NoticeToken": []
          }
        ],
        "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.",
        "x-error-codes": [
          "notice_auth_required",
          "notice_auth_expired",
          "notice_auth_revoked",
          "notice_product_mismatch",
          "delivery_instance_mismatch",
          "notice_no_longer_available",
          "notices_disabled"
        ],
        "x-source-files": [
          "routes/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "sessionId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "editor_opened",
                      "editor_available",
                      "control_clicked"
                    ]
                  },
                  "occurredAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "controlId": {
                    "type": "string"
                  },
                  "productId": {
                    "type": "integer",
                    "minimum": 1
                  }
                },
                "additionalProperties": false,
                "required": [
                  "id",
                  "sessionId",
                  "kind",
                  "occurredAt"
                ]
              }
            }
          }
        }
      }
    },
    "/api/notices/native-sessions": {
      "post": {
        "summary": "Exchange current native proof for an independent notice token",
        "description": "Send existing in-memory native proof, not a developer secret. The exchange only reads licensing identity and issues a separate notice token; it does not activate, refresh licensing, write grace timestamps or unlock audio.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: token, expiresAt, private, productId, recipientKey.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "private": {
                      "type": "boolean"
                    },
                    "productId": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "recipientKey": {
                      "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"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/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": "Public request; operation-specific verification still applies",
        "x-access-scope": "Valid existing native credential or signed validation proof bound to this product/device and live activation.",
        "x-request-fields": [
          "productId: integer (required)",
          "instanceId: string (required)",
          "credential: string",
          "validationToken: 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": [
          "notice_auth_required",
          "notice_auth_expired",
          "notice_auth_revoked",
          "notice_product_mismatch",
          "delivery_instance_mismatch",
          "notice_no_longer_available",
          "notices_disabled"
        ],
        "x-source-files": [
          "routes/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js",
          "services/pluginNoticeNativeIdentity.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "productId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "instanceId": {
                    "type": "string",
                    "maxLength": 256
                  },
                  "credential": {
                    "type": "string"
                  },
                  "validationToken": {
                    "type": "string"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "productId",
                  "instanceId"
                ],
                "anyOf": [
                  {
                    "required": [
                      "credential"
                    ]
                  },
                  {
                    "required": [
                      "validationToken"
                    ]
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/notices/next": {
      "post": {
        "summary": "Lease the next eligible notice to this editor instance",
        "description": "null means no eligible due delivery. Fetching or showing the collapsed badge is not a shown receipt. Revalidate before display/actions and release ownership when destroying the editor. Unsupported download clients receive a public details-page fallback, not a file grant.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: review the response schema below.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "deliveryId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "campaignId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "version": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "validUntil": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "shown": {
                          "type": "boolean"
                        },
                        "completedActions": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "content": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "title": {
                              "type": "string"
                            },
                            "body": {
                              "type": "string"
                            },
                            "brand": {
                              "type": "string"
                            },
                            "color": {
                              "type": "string"
                            },
                            "audience": {
                              "type": "string",
                              "enum": [
                                "public",
                                "customers"
                              ]
                            },
                            "noticeType": {
                              "type": "string",
                              "enum": [
                                "announcement",
                                "content",
                                "plugin_update",
                                "download",
                                "promotion"
                              ]
                            },
                            "trigger": {
                              "type": "string",
                              "enum": [
                                "editor_opened",
                                "editor_available",
                                "control_clicked"
                              ]
                            },
                            "controlId": {
                              "type": "string"
                            },
                            "timezone": {
                              "type": "string"
                            },
                            "startAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "endAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "delaySeconds": {
                              "type": "integer",
                              "minimum": 0,
                              "maximum": 86400
                            },
                            "priority": {
                              "type": "integer",
                              "minimum": 0,
                              "maximum": 100
                            },
                            "maxDisplays": {
                              "type": "integer",
                              "minimum": 1,
                              "maximum": 100
                            },
                            "cooldownSeconds": {
                              "type": "integer",
                              "minimum": 60,
                              "maximum": 2592000
                            },
                            "actions": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "type": {
                                    "type": "string",
                                    "enum": [
                                      "https",
                                      "navigate",
                                      "dismiss",
                                      "resource",
                                      "download",
                                      "instructions"
                                    ]
                                  },
                                  "label": {
                                    "type": "string"
                                  },
                                  "target": {
                                    "type": "string"
                                  },
                                  "presentation": {
                                    "type": "string",
                                    "enum": [
                                      "button",
                                      "link"
                                    ]
                                  },
                                  "resource": {
                                    "type": "object",
                                    "properties": {
                                      "id": {
                                        "type": "string"
                                      },
                                      "kind": {
                                        "type": "string"
                                      },
                                      "productId": {
                                        "type": "integer",
                                        "minimum": 1
                                      },
                                      "url": {
                                        "type": "string"
                                      },
                                      "downloadAvailable": {
                                        "type": "boolean"
                                      }
                                    },
                                    "additionalProperties": true
                                  }
                                },
                                "additionalProperties": true
                              },
                              "maxItems": 4
                            },
                            "action": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "type": {
                                  "type": "string",
                                  "enum": [
                                    "https",
                                    "navigate",
                                    "dismiss",
                                    "resource",
                                    "download",
                                    "instructions"
                                  ]
                                },
                                "label": {
                                  "type": "string"
                                },
                                "target": {
                                  "type": "string"
                                },
                                "presentation": {
                                  "type": "string",
                                  "enum": [
                                    "button",
                                    "link"
                                  ]
                                },
                                "resource": {
                                  "type": "object",
                                  "properties": {
                                    "id": {
                                      "type": "string"
                                    },
                                    "kind": {
                                      "type": "string"
                                    },
                                    "productId": {
                                      "type": "integer",
                                      "minimum": 1
                                    },
                                    "url": {
                                      "type": "string"
                                    },
                                    "downloadAvailable": {
                                      "type": "boolean"
                                    }
                                  },
                                  "additionalProperties": true
                                }
                              },
                              "additionalProperties": true,
                              "description": "Legacy single-action input; prefer actions for new integrations."
                            },
                            "resourceId": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "format": "uuid"
                                },
                                {
                                  "const": ""
                                }
                              ]
                            },
                            "linkedProductId": {
                              "anyOf": [
                                {
                                  "type": "integer",
                                  "minimum": 1
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "productUrl": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true,
                          "required": [
                            "name",
                            "title",
                            "body",
                            "audience",
                            "trigger",
                            "timezone",
                            "startAt",
                            "endAt",
                            "delaySeconds",
                            "priority",
                            "maxDisplays",
                            "cooldownSeconds"
                          ],
                          "anyOf": [
                            {
                              "required": [
                                "actions"
                              ]
                            },
                            {
                              "required": [
                                "action"
                              ]
                            }
                          ]
                        }
                      },
                      "additionalProperties": true
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/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": "Notice-only Bearer capability",
        "x-access-scope": "Notice-only bearer capability, matching product, recipient and editor instance; current campaign eligibility is rechecked.",
        "x-request-fields": [
          "instanceId: string (required)",
          "resourceKinds: array",
          "productId: integer",
          "contentDownloads: boolean"
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.",
        "security": [
          {
            "NoticeToken": []
          }
        ],
        "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.",
        "x-error-codes": [
          "notice_auth_required",
          "notice_auth_expired",
          "notice_auth_revoked",
          "notice_product_mismatch",
          "delivery_instance_mismatch",
          "notice_no_longer_available",
          "notices_disabled"
        ],
        "x-source-files": [
          "routes/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instanceId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "resourceKinds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "product",
                        "release",
                        "content",
                        "download"
                      ]
                    }
                  },
                  "productId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "contentDownloads": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "instanceId"
                ]
              }
            }
          }
        }
      }
    },
    "/api/notices/sessions": {
      "post": {
        "summary": "Create or renew an explicitly public notice session",
        "description": "This is anonymous notice identity, never a license or customer session. Reuse a valid existingToken to preserve the anonymous recipient. Missing/expired local state can reset anonymous frequency history. Keep tokens private and out of URLs.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/plugin-notices"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: token, expiresAt, private, productId, recipientKey.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "private": {
                      "type": "boolean"
                    },
                    "productId": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "recipientKey": {
                      "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"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/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": "Public request; operation-specific verification still applies",
        "x-access-scope": "Product notice channel and public audience must both be enabled.",
        "x-request-fields": [
          "productId: integer (required)",
          "existingToken: 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": [
          "notice_auth_required",
          "notice_auth_expired",
          "notice_auth_revoked",
          "notice_product_mismatch",
          "delivery_instance_mismatch",
          "notice_no_longer_available",
          "notices_disabled"
        ],
        "x-source-files": [
          "routes/pluginNoticeRoutes.js",
          "services/pluginNoticeService.js",
          "services/pluginNoticeContracts.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "productId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "existingToken": {
                    "type": "string"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "productId"
                ]
              }
            }
          }
        }
      }
    },
    "/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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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. environment defaults to test; live must be selected explicitly. With test fulfillment disabled, a successful test result has test_mode:true, would_fulfill:true, fulfillment_event_created:false and test_validated items with null license, entitlement and claim_url: no customer access is issued. Enabled fulfillment reports the actual item access and event result. 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. A missing Idempotency-Key is derived from the relationship and external order ID; do not change the order ID to retry. manual_issue:true identifies this portal path. Serials and claim URLs are private. This does 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: success, soundsync_order_id, external_order_id, relationship_id, source, label, financial_classification, soundsync_checkout_fee_cents, reported_total_paid_cents, currency, verification_status, fulfillment_event_created, idempotent_replay, duplicate_external_order, test_mode, would_fulfill, customer, items, manual_issue.",
            "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"
                    },
                    "label": {
                      "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"
                    },
                    "test_mode": {
                      "type": "boolean"
                    },
                    "would_fulfill": {
                      "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"
                          },
                          "reseller_sku": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "fulfillment_status": {
                            "type": "string"
                          },
                          "license": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "serial": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "redemption_status": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "description": "Private serial access when issued; null for validation-only test results."
                          },
                          "entitlement": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "id": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "status": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true
                          },
                          "claim_url": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Private customer claim URL when issued; never log or publish it."
                          },
                          "commercial_model": {
                            "type": "string"
                          },
                          "wholesale_rate_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "commission_rate_bps": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "developer_revenue_share_bps": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "expected_payable_cents": {
                            "type": "integer",
                            "minimum": 0
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "manual_issue": {
                      "const": true
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "success",
                    "manual_issue",
                    "soundsync_order_id",
                    "external_order_id",
                    "customer",
                    "items",
                    "fulfillment_event_created"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/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 session token",
        "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",
          "environment: test | live. Omitted environment defaults to test. Availability and relationship checks still apply.",
          "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": {
                  "environment": {
                    "type": "string",
                    "enum": [
                      "test",
                      "live"
                    ],
                    "default": "test",
                    "description": "Omitted environment defaults to test. Availability and relationship checks still apply."
                  },
                  "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}/statement-records/{statementId}/document": {
      "get": {
        "summary": "Download the current relationship-scoped private statement document",
        "description": "Streams the current document with its actual type and Content-Disposition filename; responses are private/no-store. A missing file needs reattachment, while transient storage failure can be retried. Keep financial and personal information out of public screenshots.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/partner-portal"
        },
        "parameters": [
          {
            "name": "relationshipId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "statementId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: application/octet-stream.",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
                "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 session token",
        "x-access-scope": "Developer partners.view with all-products scope; writes additionally partners.manage. Partner views require active eligible reseller membership and the relevant relationship.",
        "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/partnerWorkspaceRoutes.js",
          "services/partnerWorkspaceService.js",
          "services/partnerStatementDocumentService.js",
          "services/partnerStatementShape.js"
        ]
      }
    },
    "/api/partner-portal/relationships/{relationshipId}/terms/accept": {
      "post": {
        "summary": "Accept the currently reviewed relationship terms",
        "description": "Owner/admin relationship mutation capability is required. Relationship must be active, terms cannot be draft and terms_version must match the current read. Acceptance does not issue a license or collect payment.",
        "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: accepted, terms_version.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accepted": {
                      "type": "boolean"
                    },
                    "terms_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"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "Signed-in eligible reseller member, relationship/store ownership and operation-specific mutation capability.",
        "x-request-fields": [
          "accept_terms: true (required)",
          "terms_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/partnerPortalRoutes.js",
          "services/partnerHubService.js",
          "services/partnerWooCommerceService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "accept_terms": {
                    "const": true
                  },
                  "terms_version": {
                    "type": "string"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "accept_terms",
                  "terms_version"
                ]
              }
            }
          }
        }
      }
    },
    "/api/partner-portal/relationships/{relationshipId}/test-fulfillment": {
      "post": {
        "summary": "Validate a synthetic assigned-SKU setup order without issuing licenses",
        "description": "Subject to the custom fulfillment availability setting and order mutation capability. Validates a synthetic order and saves setup-test metadata; it does not issue licenses. A disabled capability returns 410 PARTNER_FULFILLMENT_DISABLED. This is a write, not a read-only audit probe.",
        "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: success, test_mode, would_fulfill, soundsync_order_id, external_order_id, relationship_id, source, verification_status, label, reported_total_paid_cents, currency, fulfillment_event_created, customer, items.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "test_mode": {
                      "type": "boolean"
                    },
                    "would_fulfill": {
                      "type": "boolean"
                    },
                    "soundsync_order_id": {
                      "type": "string"
                    },
                    "external_order_id": {
                      "type": "string"
                    },
                    "relationship_id": {
                      "type": "string"
                    },
                    "source": {
                      "type": "string"
                    },
                    "verification_status": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "reported_total_paid_cents": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "currency": {
                      "type": "string"
                    },
                    "fulfillment_event_created": {
                      "const": false
                    },
                    "customer": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "null"
                        },
                        "email": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    },
                    "items": {
                      "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"
                }
              }
            }
          },
          "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 session token",
        "x-access-scope": "Signed-in eligible reseller member, relationship/store ownership and operation-specific mutation capability.",
        "x-request-fields": [
          "reseller_sku: 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/partnerPortalRoutes.js",
          "services/partnerHubService.js",
          "services/partnerWooCommerceService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reseller_sku": {
                    "type": "string"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "reseller_sku"
                ]
              }
            }
          }
        }
      }
    },
    "/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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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}/disconnect": {
      "post": {
        "summary": "Disconnect a permitted WooCommerce store while retaining history",
        "description": "Owner/admin/technical store capability is required. Stops new fulfillment, removes saved consumer credentials and expires old authorization links. No provider request is sent; remove unused keys/webhooks in WooCommerce separately. Reconnection needs a fresh prepared connection and mapping/activation review.",
        "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",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "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 session token",
        "x-access-scope": "Signed-in eligible reseller member, relationship/store ownership and operation-specific mutation capability.",
        "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 session token",
        "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/workspace": {
      "get": {
        "summary": "Read scoped inventory, sales estimates and recorded statements",
        "description": "UTC date filters, zero-based page and 25 sales rows per page; follow has_more. Unused licenses are inventory. Redemptions are estimates, linked reported lines are counted separately, currencies are not added together and statements do not prove a SoundSync transfer.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/partner-portal"
        },
        "parameters": [
          {
            "name": "start",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "end",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "estimated",
                "reported"
              ]
            }
          },
          {
            "name": "product_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "pool_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "relationship_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: can_record_statements, relationships, filters, sales, has_more, page, summary, daily, pools, products, statements, basis.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "can_record_statements": {
                      "type": "boolean"
                    },
                    "relationships": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "filters": {
                      "type": "object",
                      "properties": {},
                      "additionalProperties": true
                    },
                    "sales": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "page": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "summary": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "daily": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "pools": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "products": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "statements": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "relationship_id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "developer_id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "partner_id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "period_start": {
                            "type": "string"
                          },
                          "period_end": {
                            "type": "string"
                          },
                          "currency": {
                            "type": "string"
                          },
                          "gross_reported_sales_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "expected_payable_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "payment_received_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "outstanding_balance_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "status": {
                            "type": "string"
                          },
                          "record_source": {
                            "type": "string"
                          },
                          "record_details": {
                            "type": "object",
                            "properties": {
                              "reference": {
                                "type": "string"
                              },
                              "notes": {
                                "type": "string"
                              },
                              "payment_date": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "document": {
                                "type": "object",
                                "properties": {
                                  "name": {
                                    "type": "string"
                                  },
                                  "bytes": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "type": {
                                    "type": "string"
                                  }
                                },
                                "additionalProperties": true
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "basis": {
                      "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 session token",
        "x-access-scope": "Developer partners.view with all-products scope; writes additionally partners.manage. Partner views require active eligible reseller membership and the relevant relationship.",
        "x-request-fields": [
          "query start: string",
          "query end: string",
          "query page: integer",
          "query kind: string",
          "query product_id: integer",
          "query pool_id: integer",
          "query relationship_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/partnerWorkspaceRoutes.js",
          "services/partnerWorkspaceService.js",
          "services/partnerStatementDocumentService.js",
          "services/partnerStatementShape.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. Custom fulfillment webhook writes require SoundSync activation and return 410 PARTNER_FULFILLMENT_DISABLED when disabled. Authorized campaign and historical reads are separate. External seller payments remain outside SoundSync-managed checkout and its sales percentage. External sellers handle their own provider costs; applicable SoundSync service and redemption charges remain separate.",
        "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. Custom fulfillment webhook writes require SoundSync activation and return 410 PARTNER_FULFILLMENT_DISABLED when disabled. Authorized campaign and historical reads are separate. External seller payments remain outside SoundSync-managed checkout and its sales percentage. External sellers handle their own provider costs; applicable SoundSync service and redemption charges remain separate.",
        "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. Custom fulfillment webhook writes require SoundSync activation and return 410 PARTNER_FULFILLMENT_DISABLED when disabled. Authorized campaign and historical reads are separate. External seller payments remain outside SoundSync-managed checkout and its sales percentage. External sellers handle their own provider costs; applicable SoundSync service and redemption charges remain separate.",
        "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. Custom fulfillment webhook writes require SoundSync activation and return 410 PARTNER_FULFILLMENT_DISABLED when disabled. Authorized campaign and historical reads are separate. External seller payments remain outside SoundSync-managed checkout and its sales percentage. External sellers handle their own provider costs; applicable SoundSync service and redemption charges remain separate.",
        "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": "Custom fulfillment requires SoundSync activation. Disabled availability returns 410 PARTNER_FULFILLMENT_DISABLED without issuing access. Test credentials normally validate only: test_mode:true and would_fulfill:true are not actual fulfillment; inspect fulfillment_event_created and item statuses. Real test fulfillment requires its separate enabled capability. External processing fees are not covered by SoundSync. 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"
                    },
                    "label": {
                      "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"
                    },
                    "test_mode": {
                      "type": "boolean"
                    },
                    "would_fulfill": {
                      "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"
                          },
                          "reseller_sku": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "fulfillment_status": {
                            "type": "string"
                          },
                          "license": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "serial": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "redemption_status": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "description": "Private serial access when issued; null for validation-only test results."
                          },
                          "entitlement": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "id": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "status": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true
                          },
                          "claim_url": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Private customer claim URL when issued; never log or publish it."
                          },
                          "commercial_model": {
                            "type": "string"
                          },
                          "wholesale_rate_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "commission_rate_bps": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "developer_revenue_share_bps": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "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"
                    },
                    "label": {
                      "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"
                    },
                    "test_mode": {
                      "type": "boolean"
                    },
                    "would_fulfill": {
                      "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"
                          },
                          "reseller_sku": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "fulfillment_status": {
                            "type": "string"
                          },
                          "license": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "serial": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "redemption_status": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "description": "Private serial access when issued; null for validation-only test results."
                          },
                          "entitlement": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "id": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "status": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true
                          },
                          "claim_url": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Private customer claim URL when issued; never log or publish it."
                          },
                          "commercial_model": {
                            "type": "string"
                          },
                          "wholesale_rate_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "commission_rate_bps": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "developer_revenue_share_bps": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "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"
                }
              }
            }
          },
          "410": {
            "description": "The requested token or saved operation has expired.",
            "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": "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-error-codes": [
          "PARTNER_FULFILLMENT_DISABLED"
        ],
        "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"
                    },
                    "label": {
                      "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"
                    },
                    "test_mode": {
                      "type": "boolean"
                    },
                    "would_fulfill": {
                      "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"
                          },
                          "reseller_sku": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "fulfillment_status": {
                            "type": "string"
                          },
                          "license": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "serial": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "redemption_status": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "description": "Private serial access when issued; null for validation-only test results."
                          },
                          "entitlement": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "id": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "status": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true
                          },
                          "claim_url": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Private customer claim URL when issued; never log or publish it."
                          },
                          "commercial_model": {
                            "type": "string"
                          },
                          "wholesale_rate_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "commission_rate_bps": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "developer_revenue_share_bps": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "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": "Custom fulfillment activation is required. Disabled availability returns 410 PARTNER_FULFILLMENT_DISABLED. Reporting an external refund is not a SoundSync-managed provider refund. 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"
                }
              }
            }
          },
          "410": {
            "description": "The requested token or saved operation has expired.",
            "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": "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-error-codes": [
          "PARTNER_FULFILLMENT_DISABLED"
        ],
        "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": "Custom fulfillment activation is required. Disabled availability returns 410 PARTNER_FULFILLMENT_DISABLED. Reporting an external refund is not a SoundSync-managed provider refund.",
        "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"
                }
              }
            }
          },
          "410": {
            "description": "The requested token or saved operation has expired.",
            "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": "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-error-codes": [
          "PARTNER_FULFILLMENT_DISABLED"
        ],
        "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": "Custom fulfillment requires SoundSync activation. Disabled availability returns 410 PARTNER_FULFILLMENT_DISABLED without issuing access. Test credentials normally validate only: test_mode:true and would_fulfill:true are not actual fulfillment; inspect fulfillment_event_created and item statuses. Real test fulfillment requires its separate enabled capability. External processing fees are not covered by SoundSync.",
        "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"
                    },
                    "label": {
                      "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"
                    },
                    "test_mode": {
                      "type": "boolean"
                    },
                    "would_fulfill": {
                      "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"
                          },
                          "reseller_sku": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "fulfillment_status": {
                            "type": "string"
                          },
                          "license": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "serial": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "redemption_status": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "description": "Private serial access when issued; null for validation-only test results."
                          },
                          "entitlement": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "id": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "status": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true
                          },
                          "claim_url": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Private customer claim URL when issued; never log or publish it."
                          },
                          "commercial_model": {
                            "type": "string"
                          },
                          "wholesale_rate_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "commission_rate_bps": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "developer_revenue_share_bps": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "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, label, financial_classification, soundsync_checkout_fee_cents, reported_total_paid_cents, currency, verification_status, fulfillment_event_created, idempotent_replay, duplicate_external_order, test_mode, would_fulfill, 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"
                    },
                    "label": {
                      "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"
                    },
                    "test_mode": {
                      "type": "boolean"
                    },
                    "would_fulfill": {
                      "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"
                          },
                          "reseller_sku": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "fulfillment_status": {
                            "type": "string"
                          },
                          "license": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "serial": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "redemption_status": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "description": "Private serial access when issued; null for validation-only test results."
                          },
                          "entitlement": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "id": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "status": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true
                          },
                          "claim_url": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Private customer claim URL when issued; never log or publish it."
                          },
                          "commercial_model": {
                            "type": "string"
                          },
                          "wholesale_rate_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "commission_rate_bps": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "developer_revenue_share_bps": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "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"
                }
              }
            }
          },
          "410": {
            "description": "The requested token or saved operation has expired.",
            "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": "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-error-codes": [
          "PARTNER_FULFILLMENT_DISABLED"
        ],
        "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, label, financial_classification, soundsync_checkout_fee_cents, reported_total_paid_cents, currency, verification_status, fulfillment_event_created, idempotent_replay, duplicate_external_order, test_mode, would_fulfill, 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"
                    },
                    "label": {
                      "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"
                    },
                    "test_mode": {
                      "type": "boolean"
                    },
                    "would_fulfill": {
                      "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"
                          },
                          "reseller_sku": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "fulfillment_status": {
                            "type": "string"
                          },
                          "license": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "serial": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "redemption_status": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true,
                            "description": "Private serial access when issued; null for validation-only test results."
                          },
                          "entitlement": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "id": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "status": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true
                          },
                          "claim_url": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Private customer claim URL when issued; never log or publish it."
                          },
                          "commercial_model": {
                            "type": "string"
                          },
                          "wholesale_rate_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "commission_rate_bps": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "developer_revenue_share_bps": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "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": "Custom fulfillment activation is required. Disabled availability returns 410 PARTNER_FULFILLMENT_DISABLED. Reporting an external refund is not a SoundSync-managed provider refund.",
        "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"
                }
              }
            }
          },
          "410": {
            "description": "The requested token or saved operation has expired.",
            "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": "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-error-codes": [
          "PARTNER_FULFILLMENT_DISABLED"
        ],
        "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": "Custom fulfillment activation is required. Disabled availability returns 410 PARTNER_FULFILLMENT_DISABLED. Reporting an external refund is not a SoundSync-managed provider refund.",
        "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"
                }
              }
            }
          },
          "410": {
            "description": "The requested token or saved operation has expired.",
            "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": "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-error-codes": [
          "PARTNER_FULFILLMENT_DISABLED"
        ],
        "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. Custom fulfillment webhook writes require SoundSync activation and return 410 PARTNER_FULFILLMENT_DISABLED when disabled. Authorized campaign and historical reads are separate. External seller payments remain outside SoundSync-managed checkout and its sales percentage. External sellers handle their own provider costs; applicable SoundSync service and redemption charges remain separate. 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. Custom fulfillment webhook writes require SoundSync activation and return 410 PARTNER_FULFILLMENT_DISABLED when disabled. Authorized campaign and historical reads are separate. External seller payments remain outside SoundSync-managed checkout and its sales percentage. External sellers handle their own provider costs; applicable SoundSync service and redemption charges remain separate. 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. Disabled custom fulfillment returns 410 PARTNER_FULFILLMENT_DISABLED. 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"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/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"
                }
              }
            }
          },
          "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": "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-error-codes": [
          "PARTNER_FULFILLMENT_DISABLED"
        ],
        "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": "Requires custom fulfillment activation; disabled availability returns 410 PARTNER_FULFILLMENT_DISABLED. 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"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/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"
                }
              }
            }
          },
          "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": "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-error-codes": [
          "PARTNER_FULFILLMENT_DISABLED"
        ],
        "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": "Requires custom fulfillment activation; disabled availability returns 410 PARTNER_FULFILLMENT_DISABLED. 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"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/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"
                }
              }
            }
          },
          "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": "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-error-codes": [
          "PARTNER_FULFILLMENT_DISABLED"
        ],
        "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/payment-method": {
      "get": {
        "summary": "GET /api/account/payment-method. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path.",
        "description": "Active compatibility alias of GET /api/account/payment-method. The same handler is used after the stricter root-path shared-session check. An alias is not a dry run or a fresh idempotency boundary. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path. Historical first-party saved-card endpoint for the signed-in shared SoundSync account, not the selected developer workspace. Uses the configured legacy Stripe client; there is no request environment selector. Store-only sessions are denied with 403 STOREFRONT_SESSION_SCOPE before Stripe or card queries. This does not create a checkout, tax quote, payout destination, Connect onboarding, transfer or automatic-execution change. Prefer the current developer Billing API for workspace billing and managed checkout for customer purchases. No saved method returns 404 No payment method found, not a 200 empty card. Returns only brand, last4, exp_month and exp_year when available, never the full card number or security code. This read contacts Stripe but does not attach a card.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/accounts"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "brand": {
                      "type": "string"
                    },
                    "last4": {
                      "type": "string"
                    },
                    "exp_month": {
                      "type": "integer"
                    },
                    "exp_year": {
                      "type": "integer"
                    }
                  },
                  "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": "AccountSession",
        "x-access-scope": "Shared SoundSync account session only at this older root path; store-only sessions return 403 STOREFRONT_SESSION_SCOPE before the canonical handler.",
        "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": [
          "STOREFRONT_SESSION_SCOPE"
        ],
        "x-source-files": [
          "routes/accountRoutes.js",
          "controllers/accountController.js",
          "middleware/authMiddleware.js",
          "services/storefrontCustomerCredentialService.js",
          "lib/stripe.js"
        ]
      },
      "post": {
        "summary": "POST /api/account/payment-method. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path.",
        "description": "Active compatibility alias of POST /api/account/payment-method. The same handler is used after the stricter root-path shared-session check. An alias is not a dry run or a fresh idempotency boundary. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path. Historical first-party saved-card endpoint for the signed-in shared SoundSync account, not the selected developer workspace. Uses the configured legacy Stripe client; there is no request environment selector. Store-only sessions are denied with 403 STOREFRONT_SESSION_SCOPE before Stripe or card queries. This does not create a checkout, tax quote, payout destination, Connect onboarding, transfer or automatic-execution change. Prefer the current developer Billing API for workspace billing and managed checkout for customer purchases. Requires a Stripe payment-method identifier, not raw card data. Can create a Stripe customer and save its ID, attach the supplied method, set the default invoice method and persist its identifier. These provider/database writes are not one atomic transaction. On an uncertain failure, inspect the saved method before retrying. A successful save does not itself collect a charge or pay a payout.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/accounts"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "brand": {
                      "type": "string"
                    },
                    "last4": {
                      "type": "string"
                    },
                    "exp_month": {
                      "type": "integer"
                    },
                    "exp_year": {
                      "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": "AccountSession",
        "x-access-scope": "Shared SoundSync account session only at this older root path; store-only sessions return 403 STOREFRONT_SESSION_SCOPE before the canonical handler.",
        "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-error-codes": [
          "STOREFRONT_SESSION_SCOPE"
        ],
        "x-source-files": [
          "routes/accountRoutes.js",
          "controllers/accountController.js",
          "middleware/authMiddleware.js",
          "services/storefrontCustomerCredentialService.js",
          "lib/stripe.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "payment_method_id": {
                    "type": "string"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "payment_method_id"
                ]
              }
            }
          }
        }
      }
    },
    "/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": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. New private-file attachments require a verified object authorized for the effective workspace and source-product assignment. Knowing another workspace storage key is not authorization. Deduplicated objects require this workspace's verified upload proof or an existing permitted product reference. New-policy file arrays cannot bypass the managed attachment workflow. Existing historical references are retained; new legacy attachments and version-file references still require ownership proof. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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-error-codes": [
          "PRODUCT_FILE_NOT_ACCESSIBLE",
          "PRODUCT_FILE_NOT_VERIFIED",
          "MANAGED_FILE_ATTACHMENT_REQUIRED"
        ],
        "x-source-files": [
          "routes/productRoutes.js",
          "controllers/productController.js",
          "services/developerProductService.js",
          "services/productCreationOnboardingService.js",
          "services/productFileOwnershipService.js",
          "services/developerServiceOptionService.js",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. New private-file attachments require a verified object authorized for the effective workspace and source-product assignment. Knowing another workspace storage key is not authorization. Deduplicated objects require this workspace's verified upload proof or an existing permitted product reference. New-policy file arrays cannot bypass the managed attachment workflow. Existing historical references are retained; new legacy attachments and version-file references still require ownership proof. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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-error-codes": [
          "PRODUCT_FILE_NOT_ACCESSIBLE",
          "PRODUCT_FILE_NOT_VERIFIED",
          "MANAGED_FILE_ATTACHMENT_REQUIRED"
        ],
        "x-source-files": [
          "routes/productRoutes.js",
          "controllers/productController.js",
          "services/developerProductService.js",
          "services/productCreationOnboardingService.js",
          "services/productFileOwnershipService.js",
          "services/developerServiceOptionService.js",
          "middleware/productManagementAccess.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": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.js"
        ]
      }
    },
    "/api/products/{id}/archive": {
      "post": {
        "summary": "Archive this product",
        "description": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.js"
        ]
      },
      "post": {
        "summary": "Schedule a product deal",
        "description": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. New private-file attachments require a verified object authorized for the effective workspace and source-product assignment. Knowing another workspace storage key is not authorization. Deduplicated objects require this workspace's verified upload proof or an existing permitted product reference. New-policy file arrays cannot bypass the managed attachment workflow. Existing historical references are retained; new legacy attachments and version-file references still require ownership proof. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor. 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"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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-error-codes": [
          "PRODUCT_FILE_NOT_ACCESSIBLE",
          "PRODUCT_FILE_NOT_VERIFIED",
          "MANAGED_FILE_ATTACHMENT_REQUIRED"
        ],
        "x-source-files": [
          "routes/productRoutes.js",
          "controllers/productController.js",
          "services/productCreationOnboardingService.js",
          "services/developerProductService.js",
          "services/productFileOwnershipService.js",
          "services/developerServiceOptionService.js",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. New private-file attachments require a verified object authorized for the effective workspace and source-product assignment. Knowing another workspace storage key is not authorization. Deduplicated objects require this workspace's verified upload proof or an existing permitted product reference. New-policy file arrays cannot bypass the managed attachment workflow. Existing historical references are retained; new legacy attachments and version-file references still require ownership proof. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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-error-codes": [
          "PRODUCT_FILE_NOT_ACCESSIBLE",
          "PRODUCT_FILE_NOT_VERIFIED",
          "MANAGED_FILE_ATTACHMENT_REQUIRED"
        ],
        "x-source-files": [
          "routes/productRoutes.js",
          "controllers/productController.js",
          "services/developerProductService.js",
          "services/productCreationOnboardingService.js",
          "services/productFileOwnershipService.js",
          "services/developerServiceOptionService.js",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.js"
        ]
      }
    },
    "/api/products/{id}/files/uploads/{jobId}/cancel": {
      "post": {
        "summary": "Cancel the upload job",
        "description": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.js"
        ]
      }
    },
    "/api/products/{id}/files/uploads/chunk-sessions": {
      "post": {
        "summary": "Start a local chunk session",
        "description": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.js"
        ]
      }
    },
    "/api/products/{id}/marketing": {
      "get": {
        "summary": "Read product-specific before-purchase page settings",
        "description": "Website Builder must already have a website. PUT submits the complete configuration with the current website revision; a stale revision returns 409 STOREFRONT_EDIT_CONFLICT. This edits product marketing, not product price, customer consent or checkout authority. Preserve the full normalized signup and design fields returned by GET. Choose one signup reward, not both a product and coupon. Product and parent requirements are retained automatically. Unknown extension fields do not bypass server validation. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/storefront/pre-purchase"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: productId, productName, revision, configuration, products, rewards, storefront.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "productId": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "productName": {
                      "type": "string"
                    },
                    "revision": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "configuration": {
                      "type": "object",
                      "properties": {
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "enabled": {
                          "type": "boolean"
                        },
                        "showBeforeCheckout": {
                          "type": "boolean"
                        },
                        "heading": {
                          "type": "string",
                          "maxLength": 100
                        },
                        "body": {
                          "type": "string",
                          "maxLength": 400
                        },
                        "continueLabel": {
                          "type": "string",
                          "maxLength": 40
                        },
                        "layout": {
                          "type": "string",
                          "enum": [
                            "grid",
                            "stacked",
                            "featured"
                          ]
                        },
                        "offers": {
                          "type": "array",
                          "maxItems": 12,
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "pattern": "^[A-Za-z0-9_-]+$",
                                "maxLength": 64
                              },
                              "productId": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "heading": {
                                "type": "string",
                                "maxLength": 100
                              },
                              "body": {
                                "type": "string",
                                "maxLength": 240
                              },
                              "badge": {
                                "type": "string",
                                "maxLength": 32
                              },
                              "requiredProductIds": {
                                "type": "array",
                                "maxItems": 14,
                                "uniqueItems": true,
                                "items": {
                                  "type": "integer",
                                  "minimum": 1
                                }
                              }
                            },
                            "additionalProperties": true,
                            "required": [
                              "id",
                              "productId"
                            ]
                          }
                        },
                        "signupEnabled": {
                          "type": "boolean"
                        },
                        "signup": {
                          "type": "object",
                          "properties": {
                            "reward": {
                              "type": "object",
                              "properties": {
                                "productEnabled": {
                                  "type": "boolean"
                                },
                                "productId": {
                                  "anyOf": [
                                    {
                                      "type": "integer",
                                      "minimum": 1
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "couponEnabled": {
                                  "type": "boolean"
                                },
                                "offerId": {
                                  "anyOf": [
                                    {
                                      "type": "integer",
                                      "minimum": 1
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    },
                    "products": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "name": {
                            "type": "string"
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "rewards": {
                      "type": "object",
                      "properties": {
                        "products": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "name": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "offers": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "name": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": true
                          }
                        }
                      },
                      "additionalProperties": true
                    },
                    "storefront": {
                      "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"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "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-error-codes": [
          "MARKETING_WEBSITE_REQUIRED",
          "PRODUCT_MARKETING_INVALID",
          "STOREFRONT_EDIT_CONFLICT",
          "PRE_PURCHASE_PRODUCT_UNAVAILABLE"
        ],
        "x-source-files": [
          "routes/productRoutes.js",
          "controllers/productMarketingController.js",
          "services/productMarketingService.js",
          "public/store/modules/storefront/prePurchase.js",
          "public/store/modules/storefront/signupForms.js",
          "middleware/productManagementAccess.js"
        ]
      },
      "put": {
        "summary": "Save product-specific before-purchase page settings",
        "description": "Website Builder must already have a website. PUT submits the complete configuration with the current website revision; a stale revision returns 409 STOREFRONT_EDIT_CONFLICT. This edits product marketing, not product price, customer consent or checkout authority. Preserve the full normalized signup and design fields returned by GET. Choose one signup reward, not both a product and coupon. Product and parent requirements are retained automatically. Unknown extension fields do not bypass server validation. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/storefront/pre-purchase"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: configuration, revision.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "configuration": {
                      "type": "object",
                      "properties": {
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "enabled": {
                          "type": "boolean"
                        },
                        "showBeforeCheckout": {
                          "type": "boolean"
                        },
                        "heading": {
                          "type": "string",
                          "maxLength": 100
                        },
                        "body": {
                          "type": "string",
                          "maxLength": 400
                        },
                        "continueLabel": {
                          "type": "string",
                          "maxLength": 40
                        },
                        "layout": {
                          "type": "string",
                          "enum": [
                            "grid",
                            "stacked",
                            "featured"
                          ]
                        },
                        "offers": {
                          "type": "array",
                          "maxItems": 12,
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "pattern": "^[A-Za-z0-9_-]+$",
                                "maxLength": 64
                              },
                              "productId": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "heading": {
                                "type": "string",
                                "maxLength": 100
                              },
                              "body": {
                                "type": "string",
                                "maxLength": 240
                              },
                              "badge": {
                                "type": "string",
                                "maxLength": 32
                              },
                              "requiredProductIds": {
                                "type": "array",
                                "maxItems": 14,
                                "uniqueItems": true,
                                "items": {
                                  "type": "integer",
                                  "minimum": 1
                                }
                              }
                            },
                            "additionalProperties": true,
                            "required": [
                              "id",
                              "productId"
                            ]
                          }
                        },
                        "signupEnabled": {
                          "type": "boolean"
                        },
                        "signup": {
                          "type": "object",
                          "properties": {
                            "reward": {
                              "type": "object",
                              "properties": {
                                "productEnabled": {
                                  "type": "boolean"
                                },
                                "productId": {
                                  "anyOf": [
                                    {
                                      "type": "integer",
                                      "minimum": 1
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "couponEnabled": {
                                  "type": "boolean"
                                },
                                "offerId": {
                                  "anyOf": [
                                    {
                                      "type": "integer",
                                      "minimum": 1
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    },
                    "revision": {
                      "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"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "products.edit plus storefront.manage and assigned-product access; gift-card rewards require all-products scope.",
        "x-request-fields": [
          "revision: integer (required)",
          "configuration: 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": [
          "MARKETING_WEBSITE_REQUIRED",
          "PRODUCT_MARKETING_INVALID",
          "STOREFRONT_EDIT_CONFLICT",
          "PRE_PURCHASE_PRODUCT_UNAVAILABLE"
        ],
        "x-source-files": [
          "routes/productRoutes.js",
          "controllers/productMarketingController.js",
          "services/productMarketingService.js",
          "public/store/modules/storefront/prePurchase.js",
          "public/store/modules/storefront/signupForms.js",
          "middleware/productManagementAccess.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "revision": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "configuration": {
                    "type": "object",
                    "properties": {
                      "productId": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "enabled": {
                        "type": "boolean"
                      },
                      "showBeforeCheckout": {
                        "type": "boolean"
                      },
                      "heading": {
                        "type": "string",
                        "maxLength": 100
                      },
                      "body": {
                        "type": "string",
                        "maxLength": 400
                      },
                      "continueLabel": {
                        "type": "string",
                        "maxLength": 40
                      },
                      "layout": {
                        "type": "string",
                        "enum": [
                          "grid",
                          "stacked",
                          "featured"
                        ]
                      },
                      "offers": {
                        "type": "array",
                        "maxItems": 12,
                        "items": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "pattern": "^[A-Za-z0-9_-]+$",
                              "maxLength": 64
                            },
                            "productId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "heading": {
                              "type": "string",
                              "maxLength": 100
                            },
                            "body": {
                              "type": "string",
                              "maxLength": 240
                            },
                            "badge": {
                              "type": "string",
                              "maxLength": 32
                            },
                            "requiredProductIds": {
                              "type": "array",
                              "maxItems": 14,
                              "uniqueItems": true,
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              }
                            }
                          },
                          "additionalProperties": true,
                          "required": [
                            "id",
                            "productId"
                          ]
                        }
                      },
                      "signupEnabled": {
                        "type": "boolean"
                      },
                      "signup": {
                        "type": "object",
                        "properties": {
                          "reward": {
                            "type": "object",
                            "properties": {
                              "productEnabled": {
                                "type": "boolean"
                              },
                              "productId": {
                                "anyOf": [
                                  {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "couponEnabled": {
                                "type": "boolean"
                              },
                              "offerId": {
                                "anyOf": [
                                  {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "additionalProperties": true
                  }
                },
                "additionalProperties": true,
                "required": [
                  "revision",
                  "configuration"
                ]
              }
            }
          }
        }
      }
    },
    "/api/products/{id}/pricing": {
      "get": {
        "summary": "Resolve the current regular and sale price",
        "description": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.js"
        ]
      }
    },
    "/api/products/{id}/protected-content": {
      "get": {
        "summary": "List the product protected content and immutable releases",
        "description": "An identity without a published release returns null releaseId, revision, status and publishedAt. Creator records expose eligibility metadata, not customer-owned/available playback fields. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/protected-content"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: releases.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "releases": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "contentId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "parentProductId": {
                            "anyOf": [
                              {
                                "type": "integer",
                                "minimum": 1
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "eligibleForFutureInclusion": {
                            "type": "boolean"
                          },
                          "releaseId": {
                            "anyOf": [
                              {
                                "type": "string",
                                "format": "uuid"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "revision": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "status": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "publishedAt": {
                            "anyOf": [
                              {
                                "type": "string",
                                "format": "date-time"
                              },
                              {
                                "type": "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 session token",
        "x-access-scope": "Owned and assigned product. products.view for release listing, products.edit for private upload steps, products.publish for packaging/publication.",
        "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/protectedContentController.js",
          "services/protectedContentUploadService.js",
          "services/catalogFileUploadJobService.js",
          "middleware/productManagementAccess.js"
        ]
      }
    },
    "/api/products/{id}/protected-content/uploads": {
      "post": {
        "summary": "Start a private protected-archive upload",
        "description": "One archive up to 512 MiB. contentId may be omitted to reuse/register the product archive identity. job.id is an opaque decimal string, not the content/release UUID. minimumHostVersion defaults to 0.0.0 if omitted; explicitly set the real requirement for your bank. This is not an ordinary plaintext download attachment. Keep upload URLs private. Use the returned upload plan; small files may receive a direct PUT while multipart uploads request individual parts. A fingerprint describes the actual complete file, not its name. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/protected-content"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: job, upload.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "pattern": "^[1-9][0-9]*$",
                          "description": "Opaque decimal upload-job identifier, not a content/release UUID."
                        },
                        "productId": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 1
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "sourceType": {
                          "type": "string"
                        },
                        "protectedContent": {
                          "type": "boolean"
                        },
                        "originalFilename": {
                          "type": "string"
                        },
                        "filename": {
                          "type": "string"
                        },
                        "storageKey": {
                          "type": "string"
                        },
                        "fileSizeBytes": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "expectedSizeBytes": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "mimeType": {
                          "type": "string"
                        },
                        "checksum": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "progress": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "errorCode": {
                          "type": "string"
                        },
                        "errorMessage": {
                          "type": "string"
                        },
                        "attachedProductFileId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "completedAt": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "date-time"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "resumable": {
                          "type": "boolean"
                        },
                        "expiresAt": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "date-time"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "additionalProperties": true
                    },
                    "upload": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string"
                        },
                        "method": {
                          "type": "string"
                        },
                        "headers": {
                          "type": "object",
                          "properties": {},
                          "additionalProperties": true
                        },
                        "multipart": {
                          "type": "boolean"
                        },
                        "partSize": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "partCount": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "completedPartNumbers": {
                          "type": "array",
                          "items": {
                            "type": "integer",
                            "minimum": 1
                          }
                        },
                        "expiresAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "resumed": {
                          "type": "boolean"
                        },
                        "completed": {
                          "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 session token",
        "x-access-scope": "Owned and assigned product. products.view for release listing, products.edit for private upload steps, products.publish for packaging/publication.",
        "x-request-fields": [
          "contentId: string",
          "revision: string (required)",
          "compatibleMajorVersions: array (required)",
          "minimumHostVersion: string",
          "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",
          "controllers/protectedContentController.js",
          "services/protectedContentUploadService.js",
          "services/catalogFileUploadJobService.js",
          "middleware/productManagementAccess.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contentId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "revision": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "compatibleMajorVersions": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 16,
                    "items": {
                      "anyOf": [
                        {
                          "type": "string",
                          "pattern": "^(0|[1-9][0-9]{0,8})$"
                        },
                        {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 999999999
                        }
                      ]
                    }
                  },
                  "minimumHostVersion": {
                    "type": "string",
                    "pattern": "^[0-9]{1,9}\\.[0-9]{1,9}\\.[0-9]{1,9}$",
                    "default": "0.0.0"
                  },
                  "filename": {
                    "type": "string",
                    "minLength": 1
                  },
                  "sizeBytes": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 536870912
                  },
                  "mimeType": {
                    "type": "string"
                  },
                  "multipart": {
                    "type": "boolean"
                  },
                  "fileFingerprint": {
                    "type": "string",
                    "pattern": "^v1:[a-f0-9]{64}$"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "revision",
                  "compatibleMajorVersions",
                  "filename",
                  "sizeBytes"
                ]
              }
            }
          }
        }
      }
    },
    "/api/products/{id}/protected-content/uploads/{jobId}/complete": {
      "post": {
        "summary": "Verify completion of the private source upload",
        "description": "This marks source-upload completion. It does not yet publish an encrypted customer release. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/protected-content"
        },
        "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.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "pattern": "^[1-9][0-9]*$",
                          "description": "Opaque decimal upload-job identifier, not a content/release UUID."
                        },
                        "productId": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 1
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "sourceType": {
                          "type": "string"
                        },
                        "protectedContent": {
                          "type": "boolean"
                        },
                        "originalFilename": {
                          "type": "string"
                        },
                        "filename": {
                          "type": "string"
                        },
                        "storageKey": {
                          "type": "string"
                        },
                        "fileSizeBytes": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "expectedSizeBytes": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "mimeType": {
                          "type": "string"
                        },
                        "checksum": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "progress": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "errorCode": {
                          "type": "string"
                        },
                        "errorMessage": {
                          "type": "string"
                        },
                        "attachedProductFileId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "completedAt": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "date-time"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "resumable": {
                          "type": "boolean"
                        },
                        "expiresAt": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "date-time"
                            },
                            {
                              "type": "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 session token",
        "x-access-scope": "Owned and assigned product. products.view for release listing, products.edit for private upload steps, products.publish for packaging/publication.",
        "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/protectedContentController.js",
          "services/protectedContentUploadService.js",
          "services/catalogFileUploadJobService.js",
          "middleware/productManagementAccess.js"
        ]
      }
    },
    "/api/products/{id}/protected-content/uploads/{jobId}/part": {
      "post": {
        "summary": "Prepare one private multipart PUT",
        "description": "Use only for the returned multipart plan. Upload the indicated bytes to its signed URL; this API call does not carry the archive bytes. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/protected-content"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: upload.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "upload": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string"
                        },
                        "method": {
                          "const": "PUT"
                        },
                        "headers": {
                          "type": "object",
                          "properties": {},
                          "additionalProperties": true
                        },
                        "sizeBytes": {
                          "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"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "Owned and assigned product. products.view for release listing, products.edit for private upload steps, products.publish for packaging/publication.",
        "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",
          "controllers/protectedContentController.js",
          "services/protectedContentUploadService.js",
          "services/catalogFileUploadJobService.js",
          "middleware/productManagementAccess.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "partNumber": {
                    "type": "integer",
                    "minimum": 1
                  }
                },
                "additionalProperties": true,
                "required": [
                  "partNumber"
                ]
              }
            }
          }
        }
      }
    },
    "/api/products/{id}/protected-content/uploads/{jobId}/publish": {
      "post": {
        "summary": "Package, sign and publish the completed protected archive",
        "description": "Creates the immutable .sspc release in managed private storage. A repeated completed publication returns its existing release. A failed attempt preserves the private source for safe recovery; do not replace a raw source file with a public download fallback. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/protected-content"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: contentId, releaseId, revision, packageHash.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contentId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "releaseId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "revision": {
                      "type": "string"
                    },
                    "packageHash": {
                      "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 session token",
        "x-access-scope": "Owned and assigned product. products.view for release listing, products.edit for private upload steps, products.publish for packaging/publication.",
        "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/protectedContentController.js",
          "services/protectedContentUploadService.js",
          "services/catalogFileUploadJobService.js",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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}/purchase-options": {
      "get": {
        "summary": "Read saved offers, deal history and migration review",
        "description": "Configure one or two distinct kinds on one product. New immutable terms/price versions do not rewrite previously accepted customer snapshots. Supply expectedVersionId when editing to detect stale state. Published offers need a published product, price and ready checkout. Published subscriptions use fourteen-day payment recovery and cancellation through the paid period. keep_products publication belongs to the existing ownership subscription-bundle workflow; this editor returns OWNERSHIP_SUBSCRIPTION_BUNDLE_REQUIRED. Future inclusion is limited to recurring linked_expansions/developer_catalog rules. Product ownership spans that product releases; technical content compatibility remains separate. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/purchase-options"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: productId, offers, deals, editorOffers, protectedContentEnabled, migrationReview, migrationNotes.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "productId": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "offers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "productId": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "developerId": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "one_time",
                              "subscription"
                            ]
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "draft",
                              "published",
                              "retired"
                            ]
                          },
                          "versionId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "version": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "price": {
                            "anyOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  "amountMinor": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "Integer minor units, not a floating-dollar amount."
                                  },
                                  "currency": {
                                    "type": "string",
                                    "description": "Three-letter currency code. Managed live checkout currently uses USD."
                                  },
                                  "billingInterval": {
                                    "anyOf": [
                                      {
                                        "type": "string",
                                        "enum": [
                                          "day",
                                          "week",
                                          "month",
                                          "year"
                                        ]
                                      },
                                      {
                                        "type": "null"
                                      }
                                    ]
                                  },
                                  "intervalCount": {
                                    "type": "integer",
                                    "minimum": 1,
                                    "maximum": 365
                                  },
                                  "renewalPolicy": {
                                    "type": "string",
                                    "enum": [
                                      "not_recurring",
                                      "locked",
                                      "current_list_v1"
                                    ]
                                  }
                                },
                                "additionalProperties": true
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "fulfillmentMode": {
                            "type": "string",
                            "enum": [
                              "permanent",
                              "access",
                              "keep_products"
                            ]
                          },
                          "inclusionScope": {
                            "type": "string",
                            "enum": [
                              "root_only",
                              "selected_products",
                              "linked_expansions",
                              "developer_catalog"
                            ]
                          },
                          "includeFuture": {
                            "type": "boolean"
                          },
                          "includedProductIds": {
                            "type": "array",
                            "items": {
                              "type": "integer",
                              "minimum": 1
                            }
                          },
                          "excludedProductIds": {
                            "type": "array",
                            "items": {
                              "type": "integer",
                              "minimum": 1
                            }
                          },
                          "terms": {
                            "type": "object",
                            "properties": {
                              "updatePolicy": {
                                "type": "string",
                                "enum": [
                                  "existing_policy",
                                  "current_major",
                                  "all_versions"
                                ],
                                "description": "Older values are accepted but new saved terms normalize to all_versions. Product ownership is not a paid-major gate."
                              },
                              "offlinePolicy": {
                                "type": "string",
                                "enum": [
                                  "existing_policy",
                                  "permanent_device",
                                  "grace",
                                  "online_only"
                                ]
                              },
                              "contentProtection": {
                                "type": "string",
                                "enum": [
                                  "protected",
                                  "download_only",
                                  "none"
                                ]
                              },
                              "trialScope": {
                                "type": "string",
                                "enum": [
                                  "root_only",
                                  "offer_contents"
                                ]
                              },
                              "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
                          },
                          "membershipPreview": {
                            "type": "object",
                            "properties": {},
                            "additionalProperties": true
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "deals": {
                      "type": "object",
                      "properties": {},
                      "additionalProperties": true
                    },
                    "editorOffers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "productId": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "developerId": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "one_time",
                              "subscription"
                            ]
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "draft",
                              "published",
                              "retired"
                            ]
                          },
                          "versionId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "version": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "price": {
                            "anyOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  "amountMinor": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "Integer minor units, not a floating-dollar amount."
                                  },
                                  "currency": {
                                    "type": "string",
                                    "description": "Three-letter currency code. Managed live checkout currently uses USD."
                                  },
                                  "billingInterval": {
                                    "anyOf": [
                                      {
                                        "type": "string",
                                        "enum": [
                                          "day",
                                          "week",
                                          "month",
                                          "year"
                                        ]
                                      },
                                      {
                                        "type": "null"
                                      }
                                    ]
                                  },
                                  "intervalCount": {
                                    "type": "integer",
                                    "minimum": 1,
                                    "maximum": 365
                                  },
                                  "renewalPolicy": {
                                    "type": "string",
                                    "enum": [
                                      "not_recurring",
                                      "locked",
                                      "current_list_v1"
                                    ]
                                  }
                                },
                                "additionalProperties": true
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "fulfillmentMode": {
                            "type": "string",
                            "enum": [
                              "permanent",
                              "access",
                              "keep_products"
                            ]
                          },
                          "inclusionScope": {
                            "type": "string",
                            "enum": [
                              "root_only",
                              "selected_products",
                              "linked_expansions",
                              "developer_catalog"
                            ]
                          },
                          "includeFuture": {
                            "type": "boolean"
                          },
                          "includedProductIds": {
                            "type": "array",
                            "items": {
                              "type": "integer",
                              "minimum": 1
                            }
                          },
                          "excludedProductIds": {
                            "type": "array",
                            "items": {
                              "type": "integer",
                              "minimum": 1
                            }
                          },
                          "terms": {
                            "type": "object",
                            "properties": {
                              "updatePolicy": {
                                "type": "string",
                                "enum": [
                                  "existing_policy",
                                  "current_major",
                                  "all_versions"
                                ],
                                "description": "Older values are accepted but new saved terms normalize to all_versions. Product ownership is not a paid-major gate."
                              },
                              "offlinePolicy": {
                                "type": "string",
                                "enum": [
                                  "existing_policy",
                                  "permanent_device",
                                  "grace",
                                  "online_only"
                                ]
                              },
                              "contentProtection": {
                                "type": "string",
                                "enum": [
                                  "protected",
                                  "download_only",
                                  "none"
                                ]
                              },
                              "trialScope": {
                                "type": "string",
                                "enum": [
                                  "root_only",
                                  "offer_contents"
                                ]
                              },
                              "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
                          },
                          "membershipPreview": {
                            "type": "object",
                            "properties": {},
                            "additionalProperties": true
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "protectedContentEnabled": {
                      "type": "boolean"
                    },
                    "migrationReview": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "migrationNotes": {
                      "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 session token",
        "x-access-scope": "Effective developer owns the product; assigned-product access applies. products.view for reads, products.edit for saves, and products.publish for publication, retirement or published-deal changes.",
        "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/purchaseOfferController.js",
          "services/purchaseOfferService.js",
          "services/purchaseOfferModel.js",
          "middleware/productManagementAccess.js"
        ]
      },
      "put": {
        "summary": "Save selected purchase options and related deal changes",
        "description": "Configure one or two distinct kinds on one product. New immutable terms/price versions do not rewrite previously accepted customer snapshots. Supply expectedVersionId when editing to detect stale state. Published offers need a published product, price and ready checkout. Published subscriptions use fourteen-day payment recovery and cancellation through the paid period. keep_products publication belongs to the existing ownership subscription-bundle workflow; this editor returns OWNERSHIP_SUBSCRIPTION_BUNDLE_REQUIRED. Future inclusion is limited to recurring linked_expansions/developer_catalog rules. Product ownership spans that product releases; technical content compatibility remains separate. Omitted kinds are not retired. Supply explicit retireOfferIds or use the retirement route. Every deals entry needs promotion or retirePromotionId for a kind included in this save. If both are supplied, retirement takes precedence. Automatic linked-expansion/catalog membership uses eligible published protected-content identities, not every ordinary listing. monthly/yearly price inputs normalize to month/year. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/purchase-options"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: offers, deals.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "offers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "productId": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "developerId": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "one_time",
                              "subscription"
                            ]
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "draft",
                              "published",
                              "retired"
                            ]
                          },
                          "versionId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "version": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "price": {
                            "anyOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  "amountMinor": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "Integer minor units, not a floating-dollar amount."
                                  },
                                  "currency": {
                                    "type": "string",
                                    "description": "Three-letter currency code. Managed live checkout currently uses USD."
                                  },
                                  "billingInterval": {
                                    "anyOf": [
                                      {
                                        "type": "string",
                                        "enum": [
                                          "day",
                                          "week",
                                          "month",
                                          "year"
                                        ]
                                      },
                                      {
                                        "type": "null"
                                      }
                                    ]
                                  },
                                  "intervalCount": {
                                    "type": "integer",
                                    "minimum": 1,
                                    "maximum": 365
                                  },
                                  "renewalPolicy": {
                                    "type": "string",
                                    "enum": [
                                      "not_recurring",
                                      "locked",
                                      "current_list_v1"
                                    ]
                                  }
                                },
                                "additionalProperties": true
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "fulfillmentMode": {
                            "type": "string",
                            "enum": [
                              "permanent",
                              "access",
                              "keep_products"
                            ]
                          },
                          "inclusionScope": {
                            "type": "string",
                            "enum": [
                              "root_only",
                              "selected_products",
                              "linked_expansions",
                              "developer_catalog"
                            ]
                          },
                          "includeFuture": {
                            "type": "boolean"
                          },
                          "includedProductIds": {
                            "type": "array",
                            "items": {
                              "type": "integer",
                              "minimum": 1
                            }
                          },
                          "excludedProductIds": {
                            "type": "array",
                            "items": {
                              "type": "integer",
                              "minimum": 1
                            }
                          },
                          "terms": {
                            "type": "object",
                            "properties": {
                              "updatePolicy": {
                                "type": "string",
                                "enum": [
                                  "existing_policy",
                                  "current_major",
                                  "all_versions"
                                ],
                                "description": "Older values are accepted but new saved terms normalize to all_versions. Product ownership is not a paid-major gate."
                              },
                              "offlinePolicy": {
                                "type": "string",
                                "enum": [
                                  "existing_policy",
                                  "permanent_device",
                                  "grace",
                                  "online_only"
                                ]
                              },
                              "contentProtection": {
                                "type": "string",
                                "enum": [
                                  "protected",
                                  "download_only",
                                  "none"
                                ]
                              },
                              "trialScope": {
                                "type": "string",
                                "enum": [
                                  "root_only",
                                  "offer_contents"
                                ]
                              },
                              "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
                          },
                          "membershipPreview": {
                            "type": "object",
                            "properties": {},
                            "additionalProperties": true
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "deals": {
                      "type": "array",
                      "items": {
                        "anyOf": [
                          {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "offerId": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "campaignId": {
                                "anyOf": [
                                  {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "active",
                                  "retired"
                                ]
                              },
                              "title": {
                                "type": "string",
                                "maxLength": 200
                              },
                              "discountType": {
                                "type": "string",
                                "enum": [
                                  "percent_bps",
                                  "amount_minor"
                                ]
                              },
                              "discountValue": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "currency": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "duration": {
                                "type": "string",
                                "enum": [
                                  "first_period",
                                  "limited_periods",
                                  "ongoing"
                                ]
                              },
                              "durationPeriods": {
                                "anyOf": [
                                  {
                                    "type": "integer",
                                    "minimum": 1,
                                    "maximum": 1200
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "startsAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "endsAt": {
                                "anyOf": [
                                  {
                                    "type": "string",
                                    "format": "date-time"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "couponCode": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "stackingPolicy": {
                                "type": "string",
                                "enum": [
                                  "exclusive",
                                  "with_sale"
                                ]
                              },
                              "eligibility": {
                                "type": "object",
                                "properties": {
                                  "newCustomersOnly": {
                                    "type": "boolean"
                                  },
                                  "returningCustomersAllowed": {
                                    "type": "boolean"
                                  }
                                },
                                "additionalProperties": true
                              }
                            },
                            "additionalProperties": true
                          },
                          {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "status": {
                                "const": "retired"
                              }
                            },
                            "additionalProperties": true,
                            "required": [
                              "id",
                              "status"
                            ]
                          }
                        ]
                      }
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "Effective developer owns the product; assigned-product access applies. products.view for reads, products.edit for saves, and products.publish for publication, retirement or published-deal changes.",
        "x-request-fields": [
          "offers: array (required)",
          "deals: array",
          "retireOfferIds: 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": [
          "PURCHASE_OPTIONS_UNAVAILABLE",
          "OFFER_CHANGED",
          "OFFER_CHECKOUT_NOT_READY",
          "PRODUCT_NOT_PUBLISHED",
          "PROTECTED_RELEASE_REQUIRED",
          "OWNERSHIP_SUBSCRIPTION_BUNDLE_REQUIRED",
          "PURCHASE_OPTION_CONFLICT"
        ],
        "x-source-files": [
          "routes/productRoutes.js",
          "controllers/purchaseOfferController.js",
          "services/purchaseOfferService.js",
          "services/purchaseOfferModel.js",
          "middleware/productManagementAccess.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "offers": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "productId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "developerId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "one_time",
                            "subscription"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "published"
                          ]
                        },
                        "versionId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "version": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "price": {
                          "anyOf": [
                            {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "format": "uuid"
                                },
                                "amountMinor": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "maximum": 9007199254740991
                                },
                                "currency": {
                                  "type": "string",
                                  "pattern": "^[A-Za-z]{3}$"
                                },
                                "billingInterval": {
                                  "anyOf": [
                                    {
                                      "type": "string",
                                      "enum": [
                                        "day",
                                        "week",
                                        "month",
                                        "year",
                                        "monthly",
                                        "yearly"
                                      ],
                                      "description": "monthly/yearly are accepted input aliases; saved responses use month/year."
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "intervalCount": {
                                  "type": "integer",
                                  "minimum": 1,
                                  "maximum": 365
                                },
                                "renewalPolicy": {
                                  "type": "string",
                                  "enum": [
                                    "not_recurring",
                                    "locked",
                                    "current_list_v1"
                                  ]
                                }
                              },
                              "additionalProperties": true,
                              "required": [
                                "amountMinor"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "fulfillmentMode": {
                          "type": "string",
                          "enum": [
                            "permanent",
                            "access",
                            "keep_products"
                          ]
                        },
                        "inclusionScope": {
                          "type": "string",
                          "enum": [
                            "root_only",
                            "selected_products",
                            "linked_expansions",
                            "developer_catalog"
                          ]
                        },
                        "includeFuture": {
                          "type": "boolean"
                        },
                        "includedProductIds": {
                          "type": "array",
                          "items": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "maxItems": 10000,
                          "uniqueItems": true
                        },
                        "excludedProductIds": {
                          "type": "array",
                          "items": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "maxItems": 10000,
                          "uniqueItems": true
                        },
                        "terms": {
                          "type": "object",
                          "properties": {
                            "updatePolicy": {
                              "type": "string",
                              "enum": [
                                "existing_policy",
                                "current_major",
                                "all_versions"
                              ],
                              "description": "Older values are accepted but new saved terms normalize to all_versions. Product ownership is not a paid-major gate."
                            },
                            "offlinePolicy": {
                              "type": "string",
                              "enum": [
                                "existing_policy",
                                "permanent_device",
                                "grace",
                                "online_only"
                              ]
                            },
                            "contentProtection": {
                              "type": "string",
                              "enum": [
                                "protected",
                                "download_only",
                                "none"
                              ]
                            },
                            "trialScope": {
                              "type": "string",
                              "enum": [
                                "root_only",
                                "offer_contents"
                              ]
                            },
                            "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
                        },
                        "membershipPreview": {
                          "type": "object",
                          "properties": {},
                          "additionalProperties": true
                        },
                        "expectedVersionId": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "refreshCurrentCollection": {
                          "type": "boolean"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "kind"
                      ],
                      "allOf": [
                        {
                          "if": {
                            "properties": {
                              "includeFuture": {
                                "const": true
                              }
                            },
                            "required": [
                              "includeFuture"
                            ]
                          },
                          "then": {
                            "properties": {
                              "kind": {
                                "const": "subscription"
                              },
                              "inclusionScope": {
                                "type": "string",
                                "enum": [
                                  "linked_expansions",
                                  "developer_catalog"
                                ]
                              }
                            },
                            "required": [
                              "inclusionScope"
                            ]
                          }
                        },
                        {
                          "if": {
                            "anyOf": [
                              {
                                "not": {
                                  "required": [
                                    "inclusionScope"
                                  ]
                                }
                              },
                              {
                                "properties": {
                                  "inclusionScope": {
                                    "const": "root_only"
                                  }
                                },
                                "required": [
                                  "inclusionScope"
                                ]
                              }
                            ]
                          },
                          "then": {
                            "properties": {
                              "includedProductIds": {
                                "maxItems": 0
                              },
                              "excludedProductIds": {
                                "maxItems": 0
                              }
                            }
                          }
                        },
                        {
                          "if": {
                            "properties": {
                              "kind": {
                                "const": "one_time"
                              }
                            },
                            "required": [
                              "kind"
                            ]
                          },
                          "then": {
                            "properties": {
                              "fulfillmentMode": {
                                "const": "permanent"
                              },
                              "price": {
                                "anyOf": [
                                  {
                                    "type": "null"
                                  },
                                  {
                                    "type": "object",
                                    "properties": {
                                      "billingInterval": {
                                        "type": "null"
                                      },
                                      "intervalCount": {
                                        "const": 1
                                      },
                                      "renewalPolicy": {
                                        "const": "not_recurring"
                                      }
                                    }
                                  }
                                ]
                              }
                            }
                          }
                        },
                        {
                          "if": {
                            "properties": {
                              "kind": {
                                "const": "subscription"
                              }
                            },
                            "required": [
                              "kind"
                            ]
                          },
                          "then": {
                            "properties": {
                              "fulfillmentMode": {
                                "type": "string",
                                "enum": [
                                  "access",
                                  "keep_products"
                                ]
                              },
                              "terms": {
                                "properties": {
                                  "offlinePolicy": {
                                    "type": "string",
                                    "enum": [
                                      "existing_policy",
                                      "grace",
                                      "online_only"
                                    ]
                                  }
                                }
                              },
                              "price": {
                                "anyOf": [
                                  {
                                    "type": "null"
                                  },
                                  {
                                    "type": "object",
                                    "properties": {
                                      "amountMinor": {
                                        "minimum": 1
                                      },
                                      "billingInterval": {
                                        "type": "string",
                                        "enum": [
                                          "day",
                                          "week",
                                          "month",
                                          "year",
                                          "monthly",
                                          "yearly"
                                        ]
                                      },
                                      "renewalPolicy": {
                                        "type": "string",
                                        "enum": [
                                          "locked",
                                          "current_list_v1"
                                        ]
                                      }
                                    }
                                  }
                                ]
                              }
                            }
                          }
                        },
                        {
                          "if": {
                            "properties": {
                              "inclusionScope": {
                                "const": "selected_products"
                              }
                            },
                            "required": [
                              "inclusionScope"
                            ]
                          },
                          "then": {
                            "properties": {
                              "includedProductIds": {
                                "minItems": 1
                              }
                            },
                            "required": [
                              "includedProductIds"
                            ]
                          }
                        },
                        {
                          "if": {
                            "properties": {
                              "status": {
                                "const": "published"
                              }
                            },
                            "required": [
                              "status"
                            ]
                          },
                          "then": {
                            "properties": {
                              "price": {
                                "type": "object"
                              }
                            },
                            "required": [
                              "price"
                            ]
                          }
                        },
                        {
                          "if": {
                            "properties": {
                              "kind": {
                                "const": "subscription"
                              },
                              "status": {
                                "const": "published"
                              }
                            },
                            "required": [
                              "kind",
                              "status"
                            ]
                          },
                          "then": {
                            "properties": {
                              "fulfillmentMode": {
                                "const": "access"
                              },
                              "terms": {
                                "properties": {
                                  "failedPaymentGraceDays": {
                                    "const": 14
                                  },
                                  "cancellationBehavior": {
                                    "const": "access_until_period_end"
                                  }
                                }
                              }
                            }
                          }
                        }
                      ]
                    },
                    "minItems": 1,
                    "maxItems": 2,
                    "allOf": [
                      {
                        "contains": {
                          "properties": {
                            "kind": {
                              "const": "one_time"
                            }
                          },
                          "required": [
                            "kind"
                          ]
                        },
                        "minContains": 0,
                        "maxContains": 1
                      },
                      {
                        "contains": {
                          "properties": {
                            "kind": {
                              "const": "subscription"
                            }
                          },
                          "required": [
                            "kind"
                          ]
                        },
                        "minContains": 0,
                        "maxContains": 1
                      }
                    ]
                  },
                  "deals": {
                    "type": "array",
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "properties": {
                        "kind": {
                          "type": "string",
                          "enum": [
                            "one_time",
                            "subscription"
                          ]
                        },
                        "promotion": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "offerId": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "campaignId": {
                              "anyOf": [
                                {
                                  "type": "integer",
                                  "minimum": 1
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "status": {
                              "type": "string",
                              "enum": [
                                "active",
                                "retired"
                              ]
                            },
                            "title": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 200,
                              "pattern": "\\S"
                            },
                            "discountType": {
                              "type": "string",
                              "enum": [
                                "percent_bps",
                                "amount_minor"
                              ]
                            },
                            "discountValue": {
                              "type": "integer",
                              "minimum": 1,
                              "maximum": 9007199254740991
                            },
                            "currency": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "duration": {
                              "type": "string",
                              "enum": [
                                "first_period",
                                "limited_periods",
                                "ongoing"
                              ]
                            },
                            "durationPeriods": {
                              "anyOf": [
                                {
                                  "type": "integer",
                                  "minimum": 1,
                                  "maximum": 1200
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "startsAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "endsAt": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "couponCode": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "pattern": "^[A-Za-z0-9_-]{0,64}$"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "stackingPolicy": {
                              "type": "string",
                              "enum": [
                                "exclusive",
                                "with_sale"
                              ]
                            },
                            "eligibility": {
                              "type": "object",
                              "properties": {
                                "newCustomersOnly": {
                                  "type": "boolean"
                                },
                                "returningCustomersAllowed": {
                                  "type": "boolean"
                                }
                              },
                              "additionalProperties": false
                            },
                            "replacesPromotionId": {
                              "type": "string",
                              "format": "uuid"
                            }
                          },
                          "additionalProperties": true,
                          "required": [
                            "title",
                            "discountType",
                            "discountValue",
                            "startsAt"
                          ],
                          "allOf": [
                            {
                              "if": {
                                "properties": {
                                  "discountType": {
                                    "const": "amount_minor"
                                  }
                                },
                                "required": [
                                  "discountType"
                                ]
                              },
                              "then": {
                                "properties": {
                                  "currency": {
                                    "type": "string",
                                    "pattern": "^[A-Za-z]{3}$"
                                  }
                                },
                                "required": [
                                  "currency"
                                ]
                              }
                            },
                            {
                              "if": {
                                "properties": {
                                  "discountType": {
                                    "const": "percent_bps"
                                  }
                                },
                                "required": [
                                  "discountType"
                                ]
                              },
                              "then": {
                                "properties": {
                                  "discountValue": {
                                    "maximum": 10000
                                  }
                                }
                              }
                            },
                            {
                              "if": {
                                "properties": {
                                  "duration": {
                                    "const": "limited_periods"
                                  }
                                },
                                "required": [
                                  "duration"
                                ]
                              },
                              "then": {
                                "properties": {
                                  "durationPeriods": {
                                    "type": "integer",
                                    "minimum": 1,
                                    "maximum": 1200
                                  }
                                },
                                "required": [
                                  "durationPeriods"
                                ]
                              }
                            },
                            {
                              "if": {
                                "properties": {
                                  "duration": {
                                    "const": "ongoing"
                                  }
                                },
                                "required": [
                                  "duration"
                                ]
                              },
                              "then": {
                                "properties": {
                                  "durationPeriods": {
                                    "type": "null"
                                  }
                                }
                              }
                            },
                            {
                              "if": {
                                "anyOf": [
                                  {
                                    "not": {
                                      "required": [
                                        "duration"
                                      ]
                                    }
                                  },
                                  {
                                    "properties": {
                                      "duration": {
                                        "const": "first_period"
                                      }
                                    },
                                    "required": [
                                      "duration"
                                    ]
                                  }
                                ]
                              },
                              "then": {
                                "properties": {
                                  "durationPeriods": {
                                    "anyOf": [
                                      {
                                        "const": 1
                                      },
                                      {
                                        "type": "null"
                                      }
                                    ]
                                  }
                                }
                              }
                            }
                          ]
                        },
                        "retirePromotionId": {
                          "type": "string",
                          "format": "uuid"
                        }
                      },
                      "additionalProperties": true,
                      "required": [
                        "kind"
                      ],
                      "anyOf": [
                        {
                          "required": [
                            "promotion"
                          ]
                        },
                        {
                          "required": [
                            "retirePromotionId"
                          ]
                        }
                      ],
                      "allOf": [
                        {
                          "if": {
                            "properties": {
                              "kind": {
                                "const": "one_time"
                              }
                            },
                            "required": [
                              "kind"
                            ]
                          },
                          "then": {
                            "properties": {
                              "promotion": {
                                "properties": {
                                  "duration": {
                                    "const": "first_period"
                                  },
                                  "durationPeriods": {
                                    "anyOf": [
                                      {
                                        "const": 1
                                      },
                                      {
                                        "type": "null"
                                      }
                                    ]
                                  }
                                }
                              }
                            }
                          }
                        }
                      ]
                    }
                  },
                  "retireOfferIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "maxItems": 2
                  }
                },
                "additionalProperties": true,
                "required": [
                  "offers"
                ]
              }
            }
          }
        }
      }
    },
    "/api/products/{id}/purchase-options/{offerId}": {
      "delete": {
        "summary": "Retire an offer without deleting accepted customer terms",
        "description": "Configure one or two distinct kinds on one product. New immutable terms/price versions do not rewrite previously accepted customer snapshots. Supply expectedVersionId when editing to detect stale state. Published offers need a published product, price and ready checkout. Published subscriptions use fourteen-day payment recovery and cancellation through the paid period. keep_products publication belongs to the existing ownership subscription-bundle workflow; this editor returns OWNERSHIP_SUBSCRIPTION_BUNDLE_REQUIRED. Future inclusion is limited to recurring linked_expansions/developer_catalog rules. Product ownership spans that product releases; technical content compatibility remains separate. Returns only id and status; GET the configuration to read the retained terms. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/purchase-options"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: id, status.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "const": "retired"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "id",
                    "status"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "Effective developer owns the product; assigned-product access applies. products.view for reads, products.edit for saves, and products.publish for publication, retirement or published-deal changes.",
        "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/purchaseOfferController.js",
          "services/purchaseOfferService.js",
          "services/purchaseOfferModel.js",
          "middleware/productManagementAccess.js"
        ]
      }
    },
    "/api/products/{id}/purchase-options/{offerId}/deals": {
      "get": {
        "summary": "Read the selected offer deals including retired entries",
        "description": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/purchase-options"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: deals.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deals": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "offerId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "campaignId": {
                            "anyOf": [
                              {
                                "type": "integer",
                                "minimum": 1
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "active",
                              "retired"
                            ]
                          },
                          "title": {
                            "type": "string",
                            "maxLength": 200
                          },
                          "discountType": {
                            "type": "string",
                            "enum": [
                              "percent_bps",
                              "amount_minor"
                            ]
                          },
                          "discountValue": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "currency": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "duration": {
                            "type": "string",
                            "enum": [
                              "first_period",
                              "limited_periods",
                              "ongoing"
                            ]
                          },
                          "durationPeriods": {
                            "anyOf": [
                              {
                                "type": "integer",
                                "minimum": 1,
                                "maximum": 1200
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "startsAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "endsAt": {
                            "anyOf": [
                              {
                                "type": "string",
                                "format": "date-time"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "couponCode": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "stackingPolicy": {
                            "type": "string",
                            "enum": [
                              "exclusive",
                              "with_sale"
                            ]
                          },
                          "eligibility": {
                            "type": "object",
                            "properties": {
                              "newCustomersOnly": {
                                "type": "boolean"
                              },
                              "returningCustomersAllowed": {
                                "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 session token",
        "x-access-scope": "Effective developer owns the product; assigned-product access applies. products.view for reads, products.edit for saves, and products.publish for publication, retirement or published-deal changes.",
        "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/purchaseOfferController.js",
          "services/purchaseOfferService.js",
          "services/purchaseOfferModel.js",
          "middleware/productManagementAccess.js"
        ]
      },
      "post": {
        "summary": "Create a versioned deal for one purchase option",
        "description": "Percent values are basis points, not whole percentages. A fixed discount uses integer minor units and matching currency. Starts and ends are timestamps; end must follow start. One-time deals cover one purchase. Recurring deals distinguish first_period, limited_periods and ongoing. Versioned automatic deals and subscription payments retain their own minimum checks; a one-time coupon reduction is checked against the final paid cart. replacesPromotionId identifies a saved deal replaced by this new immutable record. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/purchase-options"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: id, offerId, campaignId, status, title, discountType, discountValue, currency, duration, durationPeriods, startsAt, endsAt, couponCode, stackingPolicy, eligibility.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "offerId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "campaignId": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "minimum": 1
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "active",
                        "retired"
                      ]
                    },
                    "title": {
                      "type": "string",
                      "maxLength": 200
                    },
                    "discountType": {
                      "type": "string",
                      "enum": [
                        "percent_bps",
                        "amount_minor"
                      ]
                    },
                    "discountValue": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "currency": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "duration": {
                      "type": "string",
                      "enum": [
                        "first_period",
                        "limited_periods",
                        "ongoing"
                      ]
                    },
                    "durationPeriods": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 1200
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "startsAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "endsAt": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "date-time"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "couponCode": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "stackingPolicy": {
                      "type": "string",
                      "enum": [
                        "exclusive",
                        "with_sale"
                      ]
                    },
                    "eligibility": {
                      "type": "object",
                      "properties": {
                        "newCustomersOnly": {
                          "type": "boolean"
                        },
                        "returningCustomersAllowed": {
                          "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 session token",
        "x-access-scope": "Effective developer owns the product; assigned-product access applies. products.view for reads, products.edit for saves, and products.publish for publication, retirement or published-deal changes.",
        "x-request-fields": [
          "id: string",
          "offerId: string",
          "campaignId: value",
          "status: active | retired",
          "title: string (required)",
          "discountType: percent_bps | amount_minor (required)",
          "discountValue: integer (required)",
          "currency: value",
          "duration: first_period | limited_periods | ongoing",
          "durationPeriods: value",
          "startsAt: string (required)",
          "endsAt: value",
          "couponCode: value",
          "stackingPolicy: exclusive | with_sale",
          "eligibility: object",
          "replacesPromotionId: 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/purchaseOfferController.js",
          "services/purchaseOfferService.js",
          "services/purchaseOfferModel.js",
          "services/purchaseOfferPromotionService.js",
          "middleware/productManagementAccess.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "offerId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "campaignId": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": 1
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "retired"
                    ]
                  },
                  "title": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200,
                    "pattern": "\\S"
                  },
                  "discountType": {
                    "type": "string",
                    "enum": [
                      "percent_bps",
                      "amount_minor"
                    ]
                  },
                  "discountValue": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 9007199254740991
                  },
                  "currency": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "duration": {
                    "type": "string",
                    "enum": [
                      "first_period",
                      "limited_periods",
                      "ongoing"
                    ]
                  },
                  "durationPeriods": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 1200
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "startsAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "endsAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "couponCode": {
                    "anyOf": [
                      {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9_-]{0,64}$"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "stackingPolicy": {
                    "type": "string",
                    "enum": [
                      "exclusive",
                      "with_sale"
                    ]
                  },
                  "eligibility": {
                    "type": "object",
                    "properties": {
                      "newCustomersOnly": {
                        "type": "boolean"
                      },
                      "returningCustomersAllowed": {
                        "type": "boolean"
                      }
                    },
                    "additionalProperties": false
                  },
                  "replacesPromotionId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "title",
                  "discountType",
                  "discountValue",
                  "startsAt"
                ],
                "allOf": [
                  {
                    "if": {
                      "properties": {
                        "discountType": {
                          "const": "amount_minor"
                        }
                      },
                      "required": [
                        "discountType"
                      ]
                    },
                    "then": {
                      "properties": {
                        "currency": {
                          "type": "string",
                          "pattern": "^[A-Za-z]{3}$"
                        }
                      },
                      "required": [
                        "currency"
                      ]
                    }
                  },
                  {
                    "if": {
                      "properties": {
                        "discountType": {
                          "const": "percent_bps"
                        }
                      },
                      "required": [
                        "discountType"
                      ]
                    },
                    "then": {
                      "properties": {
                        "discountValue": {
                          "maximum": 10000
                        }
                      }
                    }
                  },
                  {
                    "if": {
                      "properties": {
                        "duration": {
                          "const": "limited_periods"
                        }
                      },
                      "required": [
                        "duration"
                      ]
                    },
                    "then": {
                      "properties": {
                        "durationPeriods": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 1200
                        }
                      },
                      "required": [
                        "durationPeriods"
                      ]
                    }
                  },
                  {
                    "if": {
                      "properties": {
                        "duration": {
                          "const": "ongoing"
                        }
                      },
                      "required": [
                        "duration"
                      ]
                    },
                    "then": {
                      "properties": {
                        "durationPeriods": {
                          "type": "null"
                        }
                      }
                    }
                  },
                  {
                    "if": {
                      "anyOf": [
                        {
                          "not": {
                            "required": [
                              "duration"
                            ]
                          }
                        },
                        {
                          "properties": {
                            "duration": {
                              "const": "first_period"
                            }
                          },
                          "required": [
                            "duration"
                          ]
                        }
                      ]
                    },
                    "then": {
                      "properties": {
                        "durationPeriods": {
                          "anyOf": [
                            {
                              "const": 1
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/api/products/{id}/purchase-options/{offerId}/deals/{promotionId}": {
      "delete": {
        "summary": "Retire a deal without rewriting accepted subscription pricing",
        "description": "Returns only id and status, not a complete deal record. Read the selected offer deals separately for retained history. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/purchase-options"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "promotionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: id, status.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "const": "retired"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "id",
                    "status"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "Effective developer owns the product; assigned-product access applies. products.view for reads, products.edit for saves, and products.publish for publication, retirement or published-deal changes.",
        "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/purchaseOfferController.js",
          "services/purchaseOfferService.js",
          "services/purchaseOfferModel.js",
          "services/purchaseOfferPromotionService.js",
          "middleware/productManagementAccess.js"
        ]
      }
    },
    "/api/products/{id}/release": {
      "get": {
        "summary": "Read a saved release plan, readiness and recent history",
        "description": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/product-releases"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: plan, readiness, history, worker.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "plan": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "productId": {
                              "anyOf": [
                                {
                                  "type": "integer",
                                  "minimum": 1
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "version": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "status": {
                              "type": "string"
                            },
                            "scheduledAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "timeZone": {
                              "type": "string"
                            },
                            "localTime": {
                              "type": "string"
                            },
                            "disambiguation": {
                              "type": "string"
                            },
                            "actions": {
                              "type": "object",
                              "properties": {
                                "visibility": {
                                  "type": "string",
                                  "enum": [
                                    "visible",
                                    "hidden"
                                  ]
                                },
                                "listPublicly": {
                                  "type": "boolean"
                                },
                                "storefrontPlacement": {
                                  "type": "string",
                                  "enum": [
                                    "none",
                                    "visible",
                                    "featured",
                                    "hero",
                                    "hidden"
                                  ]
                                },
                                "sale": {
                                  "type": "object",
                                  "properties": {
                                    "salePrice": {
                                      "type": [
                                        "number",
                                        "string"
                                      ]
                                    },
                                    "endsAt": {
                                      "type": "string",
                                      "format": "date-time"
                                    },
                                    "title": {
                                      "type": "string"
                                    },
                                    "currency": {
                                      "type": "string"
                                    },
                                    "saleChannelScope": {
                                      "type": "string",
                                      "enum": [
                                        "universal",
                                        "website",
                                        "marketplace"
                                      ]
                                    }
                                  },
                                  "additionalProperties": true,
                                  "required": [
                                    "salePrice",
                                    "endsAt"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "outcome": {
                              "type": "object",
                              "properties": {},
                              "additionalProperties": true
                            },
                            "attempts": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "nextAttemptAt": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "releasedAt": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "authorUserId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "workspaceId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "updatedAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "additionalProperties": true
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "readiness": {
                      "type": "object",
                      "properties": {
                        "ready": {
                          "type": "boolean"
                        },
                        "blockers": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "string"
                              },
                              "message": {
                                "type": "string"
                              },
                              "retryable": {
                                "type": "boolean"
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "setup": {
                          "type": "object",
                          "properties": {},
                          "additionalProperties": true
                        },
                        "productDraft": {
                          "type": "boolean"
                        },
                        "selling": {
                          "type": "object",
                          "properties": {},
                          "additionalProperties": true
                        },
                        "notes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "additionalProperties": true
                    },
                    "history": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "worker": {
                      "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"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "products.publish and assigned product access; storefront placement also requires storefront.manage, hero replacement all-products scope, and sale settings products.edit.",
        "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-error-codes": [
          "RELEASE_STALE_VERSION",
          "RELEASE_REVIEW_REQUIRED",
          "RELEASE_NOT_READY",
          "RELEASE_TIME_AMBIGUOUS",
          "RELEASE_TIME_NONEXISTENT",
          "RELEASE_PROCESSING"
        ],
        "x-source-files": [
          "routes/productRoutes.js",
          "services/productReleaseService.js",
          "utils/productReleaseTime.js",
          "middleware/productManagementAccess.js"
        ]
      },
      "put": {
        "summary": "Save or reschedule a reviewed draft release",
        "description": "Use expectedVersion:0 for a new plan, otherwise the saved version. Scheduling requires an unarchived publishable draft and a matching reviewed fingerprint; saving does not publish early. Execution rechecks permissions, billing, product setup and approved actions. Publication can be delayed by polling, outages or provider preparation. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/product-releases"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: plan, readiness.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "plan": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "productId": {
                              "anyOf": [
                                {
                                  "type": "integer",
                                  "minimum": 1
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "version": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "status": {
                              "type": "string"
                            },
                            "scheduledAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "timeZone": {
                              "type": "string"
                            },
                            "localTime": {
                              "type": "string"
                            },
                            "disambiguation": {
                              "type": "string"
                            },
                            "actions": {
                              "type": "object",
                              "properties": {
                                "visibility": {
                                  "type": "string",
                                  "enum": [
                                    "visible",
                                    "hidden"
                                  ]
                                },
                                "listPublicly": {
                                  "type": "boolean"
                                },
                                "storefrontPlacement": {
                                  "type": "string",
                                  "enum": [
                                    "none",
                                    "visible",
                                    "featured",
                                    "hero",
                                    "hidden"
                                  ]
                                },
                                "sale": {
                                  "type": "object",
                                  "properties": {
                                    "salePrice": {
                                      "type": [
                                        "number",
                                        "string"
                                      ]
                                    },
                                    "endsAt": {
                                      "type": "string",
                                      "format": "date-time"
                                    },
                                    "title": {
                                      "type": "string"
                                    },
                                    "currency": {
                                      "type": "string"
                                    },
                                    "saleChannelScope": {
                                      "type": "string",
                                      "enum": [
                                        "universal",
                                        "website",
                                        "marketplace"
                                      ]
                                    }
                                  },
                                  "additionalProperties": true,
                                  "required": [
                                    "salePrice",
                                    "endsAt"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "outcome": {
                              "type": "object",
                              "properties": {},
                              "additionalProperties": true
                            },
                            "attempts": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "nextAttemptAt": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "releasedAt": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "authorUserId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "workspaceId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "updatedAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "additionalProperties": true
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "readiness": {
                      "type": "object",
                      "properties": {
                        "ready": {
                          "type": "boolean"
                        },
                        "blockers": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "string"
                              },
                              "message": {
                                "type": "string"
                              },
                              "retryable": {
                                "type": "boolean"
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "setup": {
                          "type": "object",
                          "properties": {},
                          "additionalProperties": true
                        },
                        "productDraft": {
                          "type": "boolean"
                        },
                        "selling": {
                          "type": "object",
                          "properties": {},
                          "additionalProperties": true
                        },
                        "notes": {
                          "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 session token",
        "x-access-scope": "products.publish and assigned product access; storefront placement also requires storefront.manage, hero replacement all-products scope, and sale settings products.edit.",
        "x-request-fields": [
          "localTime: string (required)",
          "timeZone: string (required)",
          "disambiguation: reject | earlier | later",
          "scheduledAt: string",
          "actions: object",
          "expectedVersion: integer (required)",
          "reviewedFingerprint: 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": [
          "RELEASE_STALE_VERSION",
          "RELEASE_REVIEW_REQUIRED",
          "RELEASE_NOT_READY",
          "RELEASE_TIME_AMBIGUOUS",
          "RELEASE_TIME_NONEXISTENT",
          "RELEASE_PROCESSING"
        ],
        "x-source-files": [
          "routes/productRoutes.js",
          "services/productReleaseService.js",
          "utils/productReleaseTime.js",
          "middleware/productManagementAccess.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "localTime": {
                    "type": "string"
                  },
                  "timeZone": {
                    "type": "string"
                  },
                  "disambiguation": {
                    "type": "string",
                    "enum": [
                      "reject",
                      "earlier",
                      "later"
                    ]
                  },
                  "scheduledAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "actions": {
                    "type": "object",
                    "properties": {
                      "visibility": {
                        "type": "string",
                        "enum": [
                          "visible",
                          "hidden"
                        ]
                      },
                      "listPublicly": {
                        "type": "boolean"
                      },
                      "storefrontPlacement": {
                        "type": "string",
                        "enum": [
                          "none",
                          "visible",
                          "featured",
                          "hero",
                          "hidden"
                        ]
                      },
                      "sale": {
                        "type": "object",
                        "properties": {
                          "salePrice": {
                            "type": [
                              "number",
                              "string"
                            ]
                          },
                          "endsAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "title": {
                            "type": "string"
                          },
                          "currency": {
                            "type": "string"
                          },
                          "saleChannelScope": {
                            "type": "string",
                            "enum": [
                              "universal",
                              "website",
                              "marketplace"
                            ]
                          }
                        },
                        "additionalProperties": true,
                        "required": [
                          "salePrice",
                          "endsAt"
                        ]
                      }
                    },
                    "additionalProperties": true
                  },
                  "expectedVersion": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "reviewedFingerprint": {
                    "type": "string"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "localTime",
                  "timeZone",
                  "expectedVersion",
                  "reviewedFingerprint"
                ]
              }
            }
          }
        }
      }
    },
    "/api/products/{id}/release/cancel": {
      "post": {
        "summary": "Cancel a pending release without deleting the product",
        "description": "Cancellation competes under the product/plan lock. A completed release cannot be undone here; use ordinary product visibility controls. A processing release may already have started. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/product-releases"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: plan.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "plan": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "productId": {
                              "anyOf": [
                                {
                                  "type": "integer",
                                  "minimum": 1
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "version": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "status": {
                              "type": "string"
                            },
                            "scheduledAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "timeZone": {
                              "type": "string"
                            },
                            "localTime": {
                              "type": "string"
                            },
                            "disambiguation": {
                              "type": "string"
                            },
                            "actions": {
                              "type": "object",
                              "properties": {
                                "visibility": {
                                  "type": "string",
                                  "enum": [
                                    "visible",
                                    "hidden"
                                  ]
                                },
                                "listPublicly": {
                                  "type": "boolean"
                                },
                                "storefrontPlacement": {
                                  "type": "string",
                                  "enum": [
                                    "none",
                                    "visible",
                                    "featured",
                                    "hero",
                                    "hidden"
                                  ]
                                },
                                "sale": {
                                  "type": "object",
                                  "properties": {
                                    "salePrice": {
                                      "type": [
                                        "number",
                                        "string"
                                      ]
                                    },
                                    "endsAt": {
                                      "type": "string",
                                      "format": "date-time"
                                    },
                                    "title": {
                                      "type": "string"
                                    },
                                    "currency": {
                                      "type": "string"
                                    },
                                    "saleChannelScope": {
                                      "type": "string",
                                      "enum": [
                                        "universal",
                                        "website",
                                        "marketplace"
                                      ]
                                    }
                                  },
                                  "additionalProperties": true,
                                  "required": [
                                    "salePrice",
                                    "endsAt"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "outcome": {
                              "type": "object",
                              "properties": {},
                              "additionalProperties": true
                            },
                            "attempts": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "nextAttemptAt": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "releasedAt": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "authorUserId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "workspaceId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "updatedAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "additionalProperties": true
                        },
                        {
                          "type": "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 session token",
        "x-access-scope": "products.publish and assigned product access; storefront placement also requires storefront.manage, hero replacement all-products scope, and sale settings products.edit.",
        "x-request-fields": [
          "expectedVersion: 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-error-codes": [
          "RELEASE_STALE_VERSION",
          "RELEASE_REVIEW_REQUIRED",
          "RELEASE_NOT_READY",
          "RELEASE_TIME_AMBIGUOUS",
          "RELEASE_TIME_NONEXISTENT",
          "RELEASE_PROCESSING"
        ],
        "x-source-files": [
          "routes/productRoutes.js",
          "services/productReleaseService.js",
          "utils/productReleaseTime.js",
          "middleware/productManagementAccess.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expectedVersion": {
                    "type": "integer",
                    "minimum": 0
                  }
                },
                "additionalProperties": true,
                "required": [
                  "expectedVersion"
                ]
              }
            }
          }
        }
      }
    },
    "/api/products/{id}/release/preview": {
      "post": {
        "summary": "Review the resolved instant and current launch readiness",
        "description": "Preview is not publication or a saved plan. Supply an IANA time zone. Nonexistent DST wall times fail; repeated wall times require earlier/later or an unambiguous UTC choice. Retain the returned fingerprint and resolved scheduledAt for the reviewed save. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/product-releases"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: time, actions, readiness, fingerprint.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "time": {
                      "type": "object",
                      "properties": {
                        "scheduledAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "timeZone": {
                          "type": "string"
                        },
                        "localTime": {
                          "type": "string"
                        },
                        "disambiguation": {
                          "type": "string"
                        },
                        "display": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    },
                    "actions": {
                      "type": "object",
                      "properties": {
                        "visibility": {
                          "type": "string",
                          "enum": [
                            "visible",
                            "hidden"
                          ]
                        },
                        "listPublicly": {
                          "type": "boolean"
                        },
                        "storefrontPlacement": {
                          "type": "string",
                          "enum": [
                            "none",
                            "visible",
                            "featured",
                            "hero",
                            "hidden"
                          ]
                        },
                        "sale": {
                          "type": "object",
                          "properties": {
                            "salePrice": {
                              "type": [
                                "number",
                                "string"
                              ]
                            },
                            "endsAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "title": {
                              "type": "string"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "saleChannelScope": {
                              "type": "string",
                              "enum": [
                                "universal",
                                "website",
                                "marketplace"
                              ]
                            }
                          },
                          "additionalProperties": true,
                          "required": [
                            "salePrice",
                            "endsAt"
                          ]
                        }
                      },
                      "additionalProperties": true
                    },
                    "readiness": {
                      "type": "object",
                      "properties": {
                        "ready": {
                          "type": "boolean"
                        },
                        "blockers": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "string"
                              },
                              "message": {
                                "type": "string"
                              },
                              "retryable": {
                                "type": "boolean"
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "setup": {
                          "type": "object",
                          "properties": {},
                          "additionalProperties": true
                        },
                        "productDraft": {
                          "type": "boolean"
                        },
                        "selling": {
                          "type": "object",
                          "properties": {},
                          "additionalProperties": true
                        },
                        "notes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "additionalProperties": true
                    },
                    "fingerprint": {
                      "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 session token",
        "x-access-scope": "products.publish and assigned product access; storefront placement also requires storefront.manage, hero replacement all-products scope, and sale settings products.edit.",
        "x-request-fields": [
          "localTime: string (required)",
          "timeZone: string (required)",
          "disambiguation: reject | earlier | later",
          "scheduledAt: string",
          "actions: 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": [
          "RELEASE_STALE_VERSION",
          "RELEASE_REVIEW_REQUIRED",
          "RELEASE_NOT_READY",
          "RELEASE_TIME_AMBIGUOUS",
          "RELEASE_TIME_NONEXISTENT",
          "RELEASE_PROCESSING"
        ],
        "x-source-files": [
          "routes/productRoutes.js",
          "services/productReleaseService.js",
          "utils/productReleaseTime.js",
          "middleware/productManagementAccess.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "localTime": {
                    "type": "string"
                  },
                  "timeZone": {
                    "type": "string"
                  },
                  "disambiguation": {
                    "type": "string",
                    "enum": [
                      "reject",
                      "earlier",
                      "later"
                    ]
                  },
                  "scheduledAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "actions": {
                    "type": "object",
                    "properties": {
                      "visibility": {
                        "type": "string",
                        "enum": [
                          "visible",
                          "hidden"
                        ]
                      },
                      "listPublicly": {
                        "type": "boolean"
                      },
                      "storefrontPlacement": {
                        "type": "string",
                        "enum": [
                          "none",
                          "visible",
                          "featured",
                          "hero",
                          "hidden"
                        ]
                      },
                      "sale": {
                        "type": "object",
                        "properties": {
                          "salePrice": {
                            "type": [
                              "number",
                              "string"
                            ]
                          },
                          "endsAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "title": {
                            "type": "string"
                          },
                          "currency": {
                            "type": "string"
                          },
                          "saleChannelScope": {
                            "type": "string",
                            "enum": [
                              "universal",
                              "website",
                              "marketplace"
                            ]
                          }
                        },
                        "additionalProperties": true,
                        "required": [
                          "salePrice",
                          "endsAt"
                        ]
                      }
                    },
                    "additionalProperties": true
                  }
                },
                "additionalProperties": true,
                "required": [
                  "localTime",
                  "timeZone"
                ]
              }
            }
          }
        }
      }
    },
    "/api/products/{id}/release/retry": {
      "post": {
        "summary": "Retry an eligible blocked or failed release",
        "description": "Only blocked/failed plans are retryable. Changed ownership, product configuration, review fingerprint or readiness requires a fresh reviewed schedule instead. Retry does not bypass launch gates. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/product-releases"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: plan.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "plan": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "productId": {
                              "anyOf": [
                                {
                                  "type": "integer",
                                  "minimum": 1
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "version": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "status": {
                              "type": "string"
                            },
                            "scheduledAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "timeZone": {
                              "type": "string"
                            },
                            "localTime": {
                              "type": "string"
                            },
                            "disambiguation": {
                              "type": "string"
                            },
                            "actions": {
                              "type": "object",
                              "properties": {
                                "visibility": {
                                  "type": "string",
                                  "enum": [
                                    "visible",
                                    "hidden"
                                  ]
                                },
                                "listPublicly": {
                                  "type": "boolean"
                                },
                                "storefrontPlacement": {
                                  "type": "string",
                                  "enum": [
                                    "none",
                                    "visible",
                                    "featured",
                                    "hero",
                                    "hidden"
                                  ]
                                },
                                "sale": {
                                  "type": "object",
                                  "properties": {
                                    "salePrice": {
                                      "type": [
                                        "number",
                                        "string"
                                      ]
                                    },
                                    "endsAt": {
                                      "type": "string",
                                      "format": "date-time"
                                    },
                                    "title": {
                                      "type": "string"
                                    },
                                    "currency": {
                                      "type": "string"
                                    },
                                    "saleChannelScope": {
                                      "type": "string",
                                      "enum": [
                                        "universal",
                                        "website",
                                        "marketplace"
                                      ]
                                    }
                                  },
                                  "additionalProperties": true,
                                  "required": [
                                    "salePrice",
                                    "endsAt"
                                  ]
                                }
                              },
                              "additionalProperties": true
                            },
                            "outcome": {
                              "type": "object",
                              "properties": {},
                              "additionalProperties": true
                            },
                            "attempts": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "nextAttemptAt": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "releasedAt": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "authorUserId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "workspaceId": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "updatedAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "additionalProperties": true
                        },
                        {
                          "type": "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 session token",
        "x-access-scope": "products.publish and assigned product access; storefront placement also requires storefront.manage, hero replacement all-products scope, and sale settings products.edit.",
        "x-request-fields": [
          "expectedVersion: 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-error-codes": [
          "RELEASE_STALE_VERSION",
          "RELEASE_REVIEW_REQUIRED",
          "RELEASE_NOT_READY",
          "RELEASE_TIME_AMBIGUOUS",
          "RELEASE_TIME_NONEXISTENT",
          "RELEASE_PROCESSING"
        ],
        "x-source-files": [
          "routes/productRoutes.js",
          "services/productReleaseService.js",
          "utils/productReleaseTime.js",
          "middleware/productManagementAccess.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expectedVersion": {
                    "type": "integer",
                    "minimum": 0
                  }
                },
                "additionalProperties": true,
                "required": [
                  "expectedVersion"
                ]
              }
            }
          }
        }
      }
    },
    "/api/products/{id}/restore": {
      "post": {
        "summary": "Restore this archived product",
        "description": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.js"
        ]
      }
    },
    "/api/products/{id}/setup-status": {
      "get": {
        "summary": "Inspect incomplete product setup requirements",
        "description": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.js"
        ]
      }
    },
    "/api/products/{id}/stats": {
      "get": {
        "summary": "Read statistics for one authorized product",
        "description": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current SoundSync-wide suspension blocks new download authorization with 403 CUSTOMER_ACCOUNT_RESTRICTED. A store closure affects only that store. Already issued storage URLs expire independently.",
        "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 session token",
        "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-error-codes": [
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "CUSTOMER_STORE_CLOSED",
          "SESSION_VERIFICATION_UNAVAILABLE"
        ],
        "x-source-files": [
          "routes/productRoutes.js",
          "controllers/productController.js",
          "services/productCreationOnboardingService.js",
          "services/developerProductService.js",
          "services/customerDownloadAccountAccess.js",
          "services/customerAccountRestrictionService.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. Current SoundSync-wide suspension blocks new download authorization with 403 CUSTOMER_ACCOUNT_RESTRICTED. A store closure affects only that store. Already issued storage URLs expire independently.",
        "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 session token",
        "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-error-codes": [
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "CUSTOMER_STORE_CLOSED",
          "SESSION_VERIFICATION_UNAVAILABLE"
        ],
        "x-source-files": [
          "routes/productRoutes.js",
          "controllers/productController.js",
          "services/productCreationOnboardingService.js",
          "services/developerProductService.js",
          "services/customerDownloadAccountAccess.js",
          "services/customerAccountRestrictionService.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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/purchase-options/capabilities": {
      "get": {
        "summary": "Read purchase-option and protected-content availability",
        "description": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/purchase-options"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "HTTP 200: enabled, checkoutReady, modes, protectedContentEnabled, subscriptionDealDurations, minimumPurchaseMinor.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "checkoutReady": {
                      "type": "boolean"
                    },
                    "modes": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "one_time",
                          "subscription",
                          "both"
                        ]
                      }
                    },
                    "protectedContentEnabled": {
                      "type": "boolean"
                    },
                    "subscriptionDealDurations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "minimumPurchaseMinor": {
                      "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"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "Service failure; an uncertain side effect must be reconciled before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-authentication": "Account Bearer session token",
        "x-access-scope": "products.view in the effective 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/productRoutes.js",
          "controllers/purchaseOfferController.js",
          "services/purchaseOfferService.js",
          "services/purchaseOfferModel.js",
          "middleware/productManagementAccess.js"
        ]
      }
    },
    "/api/products/stats": {
      "get": {
        "summary": "Read authorized product statistics",
        "description": "Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.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. Current product management verifies workspace permissions and any product ownership/assignment before database writes or AI work. Creating a product or using untargeted new-product AI requires products.create and all-products scope. Existing-product edits/AI use products.edit, file operations use product_files permissions, scheduled-deal writes use marketing.manage, and purchase-option deal publication retains products.publish. Statistics require analytics.view. Publication/archival keep their dedicated permissions. The effective workspace developer owns new products; the teammate remains the audit actor.",
        "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 session token",
        "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",
          "middleware/productManagementAccess.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                },
                "required": [
                  "file"
                ],
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/profile": {
      "put": {
        "summary": "PUT /api/account/profile. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path.",
        "description": "Active compatibility alias of PUT /api/account/profile. The same handler is used after the stricter root-path shared-session check. An alias is not a dry run or a fresh idempotency boundary. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path. Names can be cleared independently. Customer email edits apply immediately to the permitted profile and are not proof of inbox verification. A store-only session updates only that store contact/credential; an email change invalidates old store sessions. Marketing contacts, supported unsent work and current contact references follow the permitted edit. A shared customer session changes the shared customer profile without overwriting saved store overrides; store edits never retarget the shared Stripe billing identity. Platform/developer email changes use the pending verified email-change flow. Issued invoices and sent messages are not rewritten; saved marketing suppressions remain in force.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/accounts"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "emailChanged": {
                      "type": "boolean"
                    },
                    "emailChangeRequested": {
                      "type": "boolean"
                    },
                    "signInRequired": {
                      "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": "AccountSession",
        "x-access-scope": "Shared SoundSync account session only at this older root path; store-only sessions return 403 STOREFRONT_SESSION_SCOPE before the canonical handler.",
        "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-error-codes": [
          "STOREFRONT_SESSION_SCOPE"
        ],
        "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/r2/upload-image": {
      "post": {
        "summary": "Upload a public image asset",
        "description": "Authentication and scope checks run before multipart buffering and storage. Send purpose and scope in the query, not multipart body fields. Uploading does not save or publish a product, campaign or website. Images/audio/helpful assets are public; paid installers and protected archives must use current private direct-upload APIs. Customers and view-only accounts cannot upload developer assets.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/uploads"
        },
        "parameters": [
          {
            "in": "query",
            "name": "uploadPurpose",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "product",
                "brand",
                "storefront",
                "marketing"
              ]
            }
          },
          {
            "in": "query",
            "name": "productId",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Product or marketing uploads only: an existing product owned by the effective workspace and assigned to this teammate. Required for selected-product uploads. Brand and storefront assets reject this override."
          },
          {
            "in": "query",
            "name": "workspaceId",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Optional active workspace selector; membership is verified by the server."
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: url, key, name, public, assetType.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "key": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "public": {
                      "type": "boolean"
                    },
                    "assetType": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "url",
                    "key",
                    "name"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "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 session token",
        "x-access-scope": "Existing product_files.manage, brand.manage, storefront.manage or marketing.manage permission for the selected purpose. Product targets also require ownership and assigned-product access. Brand and storefront assets require all-products workspace scope and reject productId overrides. Other untargeted uploads require all-products scope; a new-product upload also needs products.create.",
        "x-request-fields": [
          "query uploadPurpose: string (required)",
          "query productId: integer. Product or marketing uploads only: an existing product owned by the effective workspace and assigned to this teammate. Required for selected-product uploads. Brand and storefront assets reject this override.",
          "query workspaceId: integer. Optional active workspace selector; membership is verified by the server.",
          "file: string (required). One file field. Default byte limit 10485760; configured server limits and type validation remain authoritative."
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host 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": [
          "UPLOAD_PURPOSE_REQUIRED",
          "UPLOAD_SCOPE_INVALID",
          "INVALID_PRODUCT_ID",
          "PRODUCT_NOT_FOUND",
          "developer_team_permission_denied",
          "developer_team_all_products_scope_required",
          "UPLOAD_TOO_LARGE",
          "UNSUPPORTED_FILE_TYPE"
        ],
        "x-source-files": [
          "routes/r2UploadRoutes.js",
          "middleware/developerAssetUploadAccess.js",
          "middleware/uploadGuards.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "One file field. Default byte limit 10485760; configured server limits and type validation remain authoritative."
                  }
                },
                "additionalProperties": true,
                "required": [
                  "file"
                ]
              }
            }
          }
        }
      }
    },
    "/api/r2/upload-public-audio": {
      "post": {
        "summary": "Upload a public audio asset",
        "description": "Authentication and scope checks run before multipart buffering and storage. Send purpose and scope in the query, not multipart body fields. Uploading does not save or publish a product, campaign or website. Images/audio/helpful assets are public; paid installers and protected archives must use current private direct-upload APIs. Customers and view-only accounts cannot upload developer assets.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/uploads"
        },
        "parameters": [
          {
            "in": "query",
            "name": "uploadPurpose",
            "required": true,
            "schema": {
              "type": "string",
              "const": "product"
            }
          },
          {
            "in": "query",
            "name": "productId",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Product or marketing uploads only: an existing product owned by the effective workspace and assigned to this teammate. Required for selected-product uploads. Brand and storefront assets reject this override."
          },
          {
            "in": "query",
            "name": "workspaceId",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Optional active workspace selector; membership is verified by the server."
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: url, key, name, public, assetType.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "key": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "public": {
                      "type": "boolean"
                    },
                    "assetType": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "url",
                    "key",
                    "name"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "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 session token",
        "x-access-scope": "Existing product_files.manage, brand.manage, storefront.manage or marketing.manage permission for the selected purpose. Product targets also require ownership and assigned-product access. Brand and storefront assets require all-products workspace scope and reject productId overrides. Other untargeted uploads require all-products scope; a new-product upload also needs products.create.",
        "x-request-fields": [
          "query uploadPurpose: string (required)",
          "query productId: integer. Product or marketing uploads only: an existing product owned by the effective workspace and assigned to this teammate. Required for selected-product uploads. Brand and storefront assets reject this override.",
          "query workspaceId: integer. Optional active workspace selector; membership is verified by the server.",
          "file: string (required). One file field. Default byte limit 52428800; configured server limits and type validation remain authoritative."
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host 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": [
          "UPLOAD_PURPOSE_REQUIRED",
          "UPLOAD_SCOPE_INVALID",
          "INVALID_PRODUCT_ID",
          "PRODUCT_NOT_FOUND",
          "developer_team_permission_denied",
          "developer_team_all_products_scope_required",
          "UPLOAD_TOO_LARGE",
          "UNSUPPORTED_FILE_TYPE"
        ],
        "x-source-files": [
          "routes/r2UploadRoutes.js",
          "middleware/developerAssetUploadAccess.js",
          "middleware/uploadGuards.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "One file field. Default byte limit 52428800; configured server limits and type validation remain authoritative."
                  }
                },
                "additionalProperties": true,
                "required": [
                  "file"
                ]
              }
            }
          }
        }
      }
    },
    "/api/r2/upload-public-support-asset": {
      "post": {
        "summary": "Upload a public support asset",
        "description": "Authentication and scope checks run before multipart buffering and storage. Send purpose and scope in the query, not multipart body fields. Uploading does not save or publish a product, campaign or website. Images/audio/helpful assets are public; paid installers and protected archives must use current private direct-upload APIs. Customers and view-only accounts cannot upload developer assets.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/uploads"
        },
        "parameters": [
          {
            "in": "query",
            "name": "uploadPurpose",
            "required": true,
            "schema": {
              "type": "string",
              "const": "product"
            }
          },
          {
            "in": "query",
            "name": "productId",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Product or marketing uploads only: an existing product owned by the effective workspace and assigned to this teammate. Required for selected-product uploads. Brand and storefront assets reject this override."
          },
          {
            "in": "query",
            "name": "workspaceId",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Optional active workspace selector; membership is verified by the server."
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200: url, key, name, public, assetType.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "key": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "public": {
                      "type": "boolean"
                    },
                    "assetType": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "url",
                    "key",
                    "name"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or challenge state; inspect the route-specific code and field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "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 session token",
        "x-access-scope": "Existing product_files.manage, brand.manage, storefront.manage or marketing.manage permission for the selected purpose. Product targets also require ownership and assigned-product access. Brand and storefront assets require all-products workspace scope and reject productId overrides. Other untargeted uploads require all-products scope; a new-product upload also needs products.create.",
        "x-request-fields": [
          "query uploadPurpose: string (required)",
          "query productId: integer. Product or marketing uploads only: an existing product owned by the effective workspace and assigned to this teammate. Required for selected-product uploads. Brand and storefront assets reject this override.",
          "query workspaceId: integer. Optional active workspace selector; membership is verified by the server.",
          "file: string (required). One file field. Default byte limit 26214400; configured server limits and type validation remain authoritative."
        ],
        "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host 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": [
          "UPLOAD_PURPOSE_REQUIRED",
          "UPLOAD_SCOPE_INVALID",
          "INVALID_PRODUCT_ID",
          "PRODUCT_NOT_FOUND",
          "developer_team_permission_denied",
          "developer_team_all_products_scope_required",
          "UPLOAD_TOO_LARGE",
          "UNSUPPORTED_FILE_TYPE"
        ],
        "x-source-files": [
          "routes/r2UploadRoutes.js",
          "middleware/developerAssetUploadAccess.js",
          "middleware/uploadGuards.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "One file field. Default byte limit 26214400; configured server limits and type validation remain authoritative."
                  }
                },
                "additionalProperties": true,
                "required": [
                  "file"
                ]
              }
            }
          }
        }
      }
    },
    "/api/redeem": {
      "post": {
        "summary": "Retired legacy view; use the documented replacement",
        "description": "Always returns 410 LEGACY_REDEMPTION_RETIRED before the old handler, including with a previously issued temp_token or download_token. Submitted identity, serial and token fields are ignored. No customer record, serial claim, entitlement, usage charge, email or token is created, changed or returned. Cache-Control is private, no-store. Sign in through /account#redeem-serial and use POST /api/library/redeem-serial with its current customer-account contract. Do not replay the old request body at another URL or treat a supplied email as proof of ownership. Current native /api/license/v1 claims, library redemption, downloads, telemetry and provider webhooks are separate and unchanged. Side effects: None; no data is queried, exported or changed.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/customer-library"
        },
        "parameters": [],
        "responses": {
          "410": {
            "description": "HTTP 410: retired compatibility response with code, documentation and replacement path; no records are returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "LEGACY_REDEMPTION_RETIRED"
                    },
                    "message": {
                      "type": "string"
                    },
                    "documentation": {
                      "const": "/docs/api/customer-library"
                    },
                    "replacement": {
                      "const": "/api/library/redeem-serial"
                    },
                    "accountUrl": {
                      "const": "/account#redeem-serial"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "code",
                    "message",
                    "documentation",
                    "replacement",
                    "accountUrl"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific 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": "Retired anonymous flow; no serial, customer, entitlement or account authorization is performed.",
        "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/redemptionRoutes.js",
          "middleware/retiredRedemption.js"
        ],
        "deprecated": true
      }
    },
    "/api/redeem/complete": {
      "post": {
        "summary": "Retired legacy view; use the documented replacement",
        "description": "Always returns 410 LEGACY_REDEMPTION_RETIRED before the old handler, including with a previously issued temp_token or download_token. Submitted identity, serial and token fields are ignored. No customer record, serial claim, entitlement, usage charge, email or token is created, changed or returned. Cache-Control is private, no-store. Sign in through /account#redeem-serial and use POST /api/library/redeem-serial with its current customer-account contract. Do not replay the old request body at another URL or treat a supplied email as proof of ownership. Current native /api/license/v1 claims, library redemption, downloads, telemetry and provider webhooks are separate and unchanged. Side effects: None; no data is queried, exported or changed.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/customer-library"
        },
        "parameters": [],
        "responses": {
          "410": {
            "description": "HTTP 410: retired compatibility response with code, documentation and replacement path; no records are returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "LEGACY_REDEMPTION_RETIRED"
                    },
                    "message": {
                      "type": "string"
                    },
                    "documentation": {
                      "const": "/docs/api/customer-library"
                    },
                    "replacement": {
                      "const": "/api/library/redeem-serial"
                    },
                    "accountUrl": {
                      "const": "/account#redeem-serial"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "code",
                    "message",
                    "documentation",
                    "replacement",
                    "accountUrl"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific 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": "Retired anonymous flow; no serial, customer, entitlement or account authorization is performed.",
        "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/redemptionRoutes.js",
          "middleware/retiredRedemption.js"
        ],
        "deprecated": true
      }
    },
    "/api/redeem/initiate": {
      "post": {
        "summary": "Retired legacy view; use the documented replacement",
        "description": "Always returns 410 LEGACY_REDEMPTION_RETIRED before the old handler, including with a previously issued temp_token or download_token. Submitted identity, serial and token fields are ignored. No customer record, serial claim, entitlement, usage charge, email or token is created, changed or returned. Cache-Control is private, no-store. Sign in through /account#redeem-serial and use POST /api/library/redeem-serial with its current customer-account contract. Do not replay the old request body at another URL or treat a supplied email as proof of ownership. Current native /api/license/v1 claims, library redemption, downloads, telemetry and provider webhooks are separate and unchanged. Side effects: None; no data is queried, exported or changed.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/customer-library"
        },
        "parameters": [],
        "responses": {
          "410": {
            "description": "HTTP 410: retired compatibility response with code, documentation and replacement path; no records are returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "LEGACY_REDEMPTION_RETIRED"
                    },
                    "message": {
                      "type": "string"
                    },
                    "documentation": {
                      "const": "/docs/api/customer-library"
                    },
                    "replacement": {
                      "const": "/api/library/redeem-serial"
                    },
                    "accountUrl": {
                      "const": "/account#redeem-serial"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "code",
                    "message",
                    "documentation",
                    "replacement",
                    "accountUrl"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific 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": "Retired anonymous flow; no serial, customer, entitlement or account authorization is performed.",
        "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/redemptionRoutes.js",
          "middleware/retiredRedemption.js"
        ],
        "deprecated": true
      }
    },
    "/api/redeem/redeem/complete": {
      "post": {
        "summary": "Retired legacy view; use the documented replacement",
        "description": "Always returns 410 LEGACY_REDEMPTION_RETIRED before the old handler, including with a previously issued temp_token or download_token. Submitted identity, serial and token fields are ignored. No customer record, serial claim, entitlement, usage charge, email or token is created, changed or returned. Cache-Control is private, no-store. Sign in through /account#redeem-serial and use POST /api/library/redeem-serial with its current customer-account contract. Do not replay the old request body at another URL or treat a supplied email as proof of ownership. Current native /api/license/v1 claims, library redemption, downloads, telemetry and provider webhooks are separate and unchanged. Side effects: None; no data is queried, exported or changed.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/customer-library"
        },
        "parameters": [],
        "responses": {
          "410": {
            "description": "HTTP 410: retired compatibility response with code, documentation and replacement path; no records are returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "LEGACY_REDEMPTION_RETIRED"
                    },
                    "message": {
                      "type": "string"
                    },
                    "documentation": {
                      "const": "/docs/api/customer-library"
                    },
                    "replacement": {
                      "const": "/api/library/redeem-serial"
                    },
                    "accountUrl": {
                      "const": "/account#redeem-serial"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "code",
                    "message",
                    "documentation",
                    "replacement",
                    "accountUrl"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific 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": "Retired anonymous flow; no serial, customer, entitlement or account authorization is performed.",
        "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/redemptionRoutes.js",
          "middleware/retiredRedemption.js"
        ],
        "deprecated": true
      }
    },
    "/api/redeem/redeem/initiate": {
      "post": {
        "summary": "Retired legacy view; use the documented replacement",
        "description": "Always returns 410 LEGACY_REDEMPTION_RETIRED before the old handler, including with a previously issued temp_token or download_token. Submitted identity, serial and token fields are ignored. No customer record, serial claim, entitlement, usage charge, email or token is created, changed or returned. Cache-Control is private, no-store. Sign in through /account#redeem-serial and use POST /api/library/redeem-serial with its current customer-account contract. Do not replay the old request body at another URL or treat a supplied email as proof of ownership. Current native /api/license/v1 claims, library redemption, downloads, telemetry and provider webhooks are separate and unchanged. Side effects: None; no data is queried, exported or changed.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/customer-library"
        },
        "parameters": [],
        "responses": {
          "410": {
            "description": "HTTP 410: retired compatibility response with code, documentation and replacement path; no records are returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "LEGACY_REDEMPTION_RETIRED"
                    },
                    "message": {
                      "type": "string"
                    },
                    "documentation": {
                      "const": "/docs/api/customer-library"
                    },
                    "replacement": {
                      "const": "/api/library/redeem-serial"
                    },
                    "accountUrl": {
                      "const": "/account#redeem-serial"
                    }
                  },
                  "additionalProperties": true,
                  "required": [
                    "code",
                    "message",
                    "documentation",
                    "replacement",
                    "accountUrl"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific 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": "Retired anonymous flow; no serial, customer, entitlement or account authorization is performed.",
        "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/redemptionRoutes.js",
          "middleware/retiredRedemption.js"
        ],
        "deprecated": 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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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/security": {
      "get": {
        "summary": "GET /api/account/security. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path.",
        "description": "Active compatibility alias of GET /api/account/security. The same handler is used after the stricter root-path shared-session check. An alias is not a dry run or a fresh idempotency boundary. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path. Shared-account responses retain the saved customer, developer, owner, admin, support or reseller role; legacy rows without a role use the existing admin/reseller fallback. This identity label does not grant workspace permissions. A store-only session returns user.storefrontSession:true, its store identifiers, security.storefrontOnly:true and sharedAccountSettingsAvailable:false instead of shared two-factor or session counts. Use shared sign-in for global security settings. A failed session-count query returns 500 Failed to load security settings instead of presenting a fabricated zero. Treat the count as unavailable on failure; a successful response reports the saved-session count, not proof that every session is currently online.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/accounts"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "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",
                          "description": "The saved personal account role, not a workspace membership role or authorization grant."
                        },
                        "storefrontSession": {
                          "type": "boolean"
                        },
                        "storefrontDeveloperId": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "storefrontCustomerId": {
                          "type": "integer",
                          "minimum": 1
                        }
                      },
                      "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"
                          ]
                        },
                        "storefrontOnly": {
                          "type": "boolean"
                        },
                        "sharedAccountSettingsAvailable": {
                          "type": "boolean"
                        }
                      },
                      "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": "AccountSession",
        "x-access-scope": "Shared SoundSync account session only at this older root path; store-only sessions return 403 STOREFRONT_SESSION_SCOPE before the canonical handler.",
        "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-error-codes": [
          "STOREFRONT_SESSION_SCOPE"
        ],
        "x-source-files": [
          "routes/accountRoutes.js",
          "controllers/accountController.js",
          "services/storefrontCustomerCredentialService.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 session token",
        "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": "Retired legacy view; use the documented replacement",
        "description": "This read/export view is retired. Existing filters are ignored. Use /api/developer/serials with its current authentication, permissions, filters and response shape. Serial generation, redemption, downloads and guarded serial actions are not retired by this change. Side effects: None; no data is queried, exported or changed.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/serials"
        },
        "parameters": [],
        "responses": {
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "410": {
            "description": "HTTP 410: retired compatibility response with code, documentation and replacement path; no records are returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "LEGACY_SERIAL_VIEW_RETIRED"
                    },
                    "message": {
                      "type": "string"
                    },
                    "documentation": {
                      "type": "string"
                    },
                    "replacement": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message",
                    "documentation",
                    "replacement"
                  ],
                  "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": "Account Bearer session token",
        "x-access-scope": "Retired compatibility response only; no customer, serial or transaction records are queried.",
        "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"
        ],
        "deprecated": true
      }
    },
    "/api/serials/customers-list": {
      "get": {
        "summary": "Retired legacy view; use the documented replacement",
        "description": "This read/export view is retired. Existing filters are ignored. Use /api/developer/customers with its current authentication, permissions, filters and response shape. Serial generation, redemption, downloads and guarded serial actions are not retired by this change. Side effects: None; no data is queried, exported or changed.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/serials"
        },
        "parameters": [],
        "responses": {
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "410": {
            "description": "HTTP 410: retired compatibility response with code, documentation and replacement path; no records are returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "LEGACY_SERIAL_VIEW_RETIRED"
                    },
                    "message": {
                      "type": "string"
                    },
                    "documentation": {
                      "type": "string"
                    },
                    "replacement": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message",
                    "documentation",
                    "replacement"
                  ],
                  "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": "Account Bearer session token",
        "x-access-scope": "Retired compatibility response only; no customer, serial or transaction records are queried.",
        "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"
        ],
        "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 session token",
        "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. Current SoundSync-wide suspension blocks new download authorization with 403 CUSTOMER_ACCOUNT_RESTRICTED. A store closure affects only that store. Already issued storage URLs expire independently.",
        "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 session token + 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-error-codes": [
          "CUSTOMER_ACCOUNT_RESTRICTED",
          "CUSTOMER_STORE_CLOSED",
          "SESSION_VERIFICATION_UNAVAILABLE"
        ],
        "x-source-files": [
          "routes/serialRoutes.js",
          "controllers/serialController.js",
          "services/customerDownloadAccountAccess.js",
          "services/customerAccountRestrictionService.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 session token",
        "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 session token",
        "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": "Retired legacy view; use the documented replacement",
        "description": "This read/export view is retired. Existing filters are ignored. Use /api/developer/serials/export with its current authentication, permissions, filters and response shape. Serial generation, redemption, downloads and guarded serial actions are not retired by this change. Side effects: None; no data is queried, exported or changed.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/serials"
        },
        "parameters": [],
        "responses": {
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "410": {
            "description": "HTTP 410: retired compatibility response with code, documentation and replacement path; no records are returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "LEGACY_SERIAL_VIEW_RETIRED"
                    },
                    "message": {
                      "type": "string"
                    },
                    "documentation": {
                      "type": "string"
                    },
                    "replacement": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message",
                    "documentation",
                    "replacement"
                  ],
                  "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": "Account Bearer session token",
        "x-access-scope": "Retired compatibility response only; no customer, serial or transaction records are queried.",
        "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"
        ],
        "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 session token",
        "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 session token",
        "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-available": {
      "post": {
        "summary": "Import unredeemed owned-product serial inventory from a legacy CSV",
        "description": "Required CSV columns: Serial and Product. Optional: Promo Price, Promo Expires, Batch Tag, Active From, Active To, Notes. Unknown/unowned products, missing required values and duplicate codes are skipped. count is inserted inventory, not customer ownership or a per-row report. Inserts commit per row; a later 500 can leave earlier rows imported. Inspect inventory before retrying.",
        "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 session token",
        "x-access-scope": "serials.manage and all-products workspace scope; Product must match an owned product name.",
        "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/importAvailableSerialsRoute.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"
                  }
                },
                "additionalProperties": true,
                "required": [
                  "file"
                ]
              }
            }
          }
        }
      }
    },
    "/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 session token",
        "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 session token",
        "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 session token",
        "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": "Retired legacy view; use the documented replacement",
        "description": "This read/export view is retired. Existing filters are ignored. Use /api/developer/serials with its current authentication, permissions, filters and response shape. Serial generation, redemption, downloads and guarded serial actions are not retired by this change. Side effects: None; no data is queried, exported or changed.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/serials"
        },
        "parameters": [],
        "responses": {
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "410": {
            "description": "HTTP 410: retired compatibility response with code, documentation and replacement path; no records are returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "LEGACY_SERIAL_VIEW_RETIRED"
                    },
                    "message": {
                      "type": "string"
                    },
                    "documentation": {
                      "type": "string"
                    },
                    "replacement": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message",
                    "documentation",
                    "replacement"
                  ],
                  "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": "Account Bearer session token",
        "x-access-scope": "Retired compatibility response only; no customer, serial or transaction records are queried.",
        "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"
        ],
        "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 session token",
        "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": "Retired legacy view; use the documented replacement",
        "description": "This read/export view is retired. Existing filters are ignored. Use /api/developer/partners/resellers with its current authentication, permissions, filters and response shape. Serial generation, redemption, downloads and guarded serial actions are not retired by this change. Side effects: None; no data is queried, exported or changed.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/serials"
        },
        "parameters": [],
        "responses": {
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "410": {
            "description": "HTTP 410: retired compatibility response with code, documentation and replacement path; no records are returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "LEGACY_SERIAL_VIEW_RETIRED"
                    },
                    "message": {
                      "type": "string"
                    },
                    "documentation": {
                      "type": "string"
                    },
                    "replacement": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message",
                    "documentation",
                    "replacement"
                  ],
                  "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": "Account Bearer session token",
        "x-access-scope": "Retired compatibility response only; no customer, serial or transaction records are queried.",
        "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"
        ],
        "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 session token",
        "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 session token",
        "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": "Retired legacy view; use the documented replacement",
        "description": "This read/export view is retired. Existing filters are ignored. Use /api/developer/purchases with its current authentication, permissions, filters and response shape. Serial generation, redemption, downloads and guarded serial actions are not retired by this change. Side effects: None; no data is queried, exported or changed.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/serials"
        },
        "parameters": [],
        "responses": {
          "401": {
            "description": "Missing, invalid, or expired authentication.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "Authenticated context is not permitted for this operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "410": {
            "description": "HTTP 410: retired compatibility response with code, documentation and replacement path; no records are returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "LEGACY_SERIAL_VIEW_RETIRED"
                    },
                    "message": {
                      "type": "string"
                    },
                    "documentation": {
                      "type": "string"
                    },
                    "replacement": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message",
                    "documentation",
                    "replacement"
                  ],
                  "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": "Account Bearer session token",
        "x-access-scope": "Retired compatibility response only; no customer, serial or transaction records are queried.",
        "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"
        ],
        "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": "Request confirmation from the built-in page or footer newsletter form",
        "description": "Built-in page/footer forms retain their existing fields, copy, submission and confirmation behavior. Popup campaigns use the separate claim endpoint. Pending contacts are not subscribed until confirmation. emailSent means provider acceptance, not inbox delivery. This endpoint does not restore an unsubscribed contact. Existing email_footer consent-source compatibility is retained. 503 preserves input for retry. Side effects: Adds developer-scoped marketing/contact activity subject to consent and suppression rules.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/embed-content"
        },
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "HTTP 201: subscribed, pending, alreadySubscribed, verificationRequired, emailSent, contactId.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "subscribed": {
                      "type": "boolean"
                    },
                    "pending": {
                      "type": "boolean"
                    },
                    "alreadySubscribed": {
                      "type": "boolean"
                    },
                    "verificationRequired": {
                      "type": "boolean"
                    },
                    "emailSent": {
                      "type": "boolean"
                    },
                    "contactId": {
                      "type": [
                        "integer",
                        "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"
                }
              }
            }
          },
          "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": "Public request; operation-specific verification still applies",
        "x-access-scope": "Public published storefront; developer ownership is resolved from the slug.",
        "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/websitePageService.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/status": {
      "get": {
        "summary": "Suppress invitations for the current authenticated newsletter identity",
        "description": "Returns only suppress:boolean, with Cache-Control:no-store. No/invalid identity returns suppress:false. Email, customer IDs and query tokens are ignored. Suppresses confirmed, recently accepted pending, and blocked identities for this developer; does not change consent or reveal contact data.",
        "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: suppress.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "suppress": {
                      "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"
                }
              }
            }
          },
          "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": "Optional authenticated customer/library Bearer identity; no arbitrary customer lookup.",
        "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}/newsletter/verify": {
      "get": {
        "summary": "Confirm a newsletter subscription using the private link",
        "description": "Retains the existing built-in newsletter confirmation behavior. Do not poll, health-check, log or share this URL. Returns HTML success/error, not a customer session. This confirmation is distinct from purchase-related audience enrollment and does not override suppressions. Popup verification and resubscription use the separate popup endpoint.",
        "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}/popups/{popupId}/claim": {
      "post": {
        "summary": "Request verification for a newsletter or automatic reward popup",
        "description": "Only published campaign fields/rewards are honored. No customer login account or reward is created before email verification. Promotional announcement popups do not collect email and cannot be claimed. Newsletter enrollment for reward popups is optional, explicitly checked, and never implied by reward collection. Six recipient and 60 IP/storefront popup requests per 15 minutes are allowed. Provider acceptance is not proof of delivery. Responses do not reveal existing accounts or rewards.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/embed-content"
        },
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "popupId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "HTTP 201: pending, verificationRequired, emailSent, reusedConfirmation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pending": {
                      "type": "boolean"
                    },
                    "verificationRequired": {
                      "type": "boolean"
                    },
                    "emailSent": {
                      "type": "boolean"
                    },
                    "reusedConfirmation": {
                      "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"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/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"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific 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, enabled campaign with an active date window.",
        "x-request-fields": [
          "email: string (required)",
          "firstName: string",
          "lastName: string",
          "newsletterOptIn: 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/storefrontRoutes.js",
          "services/storefrontPopupService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 320
                  },
                  "firstName": {
                    "type": "string",
                    "maxLength": 90
                  },
                  "lastName": {
                    "type": "string",
                    "maxLength": 90
                  },
                  "newsletterOptIn": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "email"
                ],
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/storefronts/{slug}/popups/setup": {
      "post": {
        "summary": "Read verified reward identity for account setup",
        "description": "Returns only the verified claim identity for prefilling account setup, with no-store caching. Does not create an account or login session. Customer registration may submit popupClaimToken with the same email and storefrontSlug; valid proof avoids a second verification email after the user explicitly supplies account details/password. Pending, expired, consumed, different-email and different-store proofs cannot verify registration. Existing accounts are never overwritten.",
        "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: email, firstName, lastName.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "email": {
                      "type": "string"
                    },
                    "firstName": {
                      "type": "string"
                    },
                    "lastName": {
                      "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"
                }
              }
            }
          },
          "429": {
            "description": "Request or operation limit reached; do not create duplicate financial work.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Operation-specific 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": "Unexpired, verified claim token for this storefront.",
        "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/storefrontRoutes.js",
          "services/storefrontPopupService.js"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  }
                },
                "required": [
                  "token"
                ],
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/storefronts/{slug}/popups/verify": {
      "get": {
        "summary": "Verify email, award once, then offer account setup",
        "description": "48-hour links award a canonical product entitlement/serial or customer-bound coupon using a Purchase Reward template, without requiring a purchase or creating a users login account. Replays do not duplicate rewards or renew later-unsubscribed consent. Account setup follows the award; existing customers sign in. Changed/unavailable rewards, store closures and disabled customers are rejected. No automatic login is issued. Treat tokens as private credentials: do not poll, log or share them.",
        "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"
                }
              }
            }
          },
          "403": {
            "description": "Access, identity, or product eligibility was denied.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "The permitted resource or account was not found.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "409": {
            "description": "Current state conflicts with the requested change; reload and reconcile before retrying.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "410": {
            "description": "The requested token or saved operation has expired.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "A required service is temporarily unavailable; inspect the failure 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": "Private verification link scoped to a popup claim and storefront.",
        "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/storefrontPopupService.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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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 session token",
        "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/update-password": {
      "post": {
        "summary": "POST /api/account/update-password. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path.",
        "description": "Active compatibility alias of POST /api/account/update-password. The same handler is used after the stricter root-path shared-session check. An alias is not a dry run or a fresh idempotency boundary. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path. Send currentPassword (or oldPassword) and newPassword. A store-only session changes only its store password and returns signInRequired:true; sign in again to that store. Shared SoundSync passwords and other stores are untouched. Shared-account verification, replacement and other-session revocation remain transactional: a failed revocation rolls the change back, and the recognized current token is retained where present. Passwords must use at least 8 characters and fit within 72 UTF-8 bytes.",
        "externalDocs": {
          "url": "https://www.soundsync.dev/docs/api/accounts"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "See the linked operation reference for the response contract.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "signInRequired": {
                      "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": "AccountSession",
        "x-access-scope": "Shared SoundSync account session only at this older root path; store-only sessions return 403 STOREFRONT_SESSION_SCOPE before the canonical handler.",
        "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-error-codes": [
          "STOREFRONT_SESSION_SCOPE"
        ],
        "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
              }
            }
          }
        }
      }
    }
  }
}
