Practical setup notes for API customers and Widgets V2 publishers.
Help & FAQ
Practical help for SoccersAPI and Widgets V2
Use this page to avoid the common setup mistakes: unsaved widget configurations, wrong domains, stale embed files, plan limits and API base URLs.
Create widget
Open the admin and create a saved Widgets V2 configuration.
Compare plans
Review API and Widgets V2 plan paths.
Contact support
Send us your uid, widget-id, domain and expected traffic.
Check domains
Confirm production domains before copying the embed code.
Getting started
What should I use first: API or Widgets V2?
Use the API when you are building a custom product and need JSON data. Use Widgets V2 when you want ready-made live score, match, league, team or player screens that can be configured and embedded quickly.
Where do I create a widget?
Create an account in the SoccersAPI admin, open the Widgets V2 configurator, choose the widget type, set domains and leagues, adjust the UI, save the configuration and then copy the generated code.
Why is saving important before copying code?
The embed loads the saved widget configuration by uid and widget-id. If the configuration is not saved or published yet, the iframe can return widget_not_found or show older settings.
Embeds and delivery
How does the free iframe work?
The free plan uses an iframe hosted on embed.soccersapi.com. It is the fastest and safest delivery path for simple installs and supports a height parameter such as height=1200.
When should I use the native web component?
Use the native web component on paid plans when SEO, cleaner routing and deeper site integration matter. The script should be loaded from static.soccersapi.com/widgets/ls-soccersapi/ls-soccersapi.umd.js.
Why does the widget look different from the configurator?
The configurator and embed must use the same saved config and the same built widget bundle. If the server still serves an old bundle or stale free.html, styling such as entity headers, modal padding or Pro options can differ.
Domains, plans and limits
Why does my domain not work?
Add the exact domain in the widget configuration and save it before testing. Domain validation checks the parent domain for iframe delivery and the current host for native widgets.
What happens if I select more leagues than my plan allows?
The saved configuration can hold the selected ids, but effective access should follow the active plan. In practice the widget and API should only deliver leagues allowed by the billing plan.
How are traffic limits handled?
Widgets use heartbeat and traffic tracking so the platform can measure usage, warn around high consumption and enforce plan limits when needed.
Troubleshooting
The iframe says widget_not_found. What should I check?
Confirm the uid, widget-id and saved configuration. The most common cause is copying the embed before saving the widget setup in the admin.
The iframe loads blank or shows $1 is not defined. What does that mean?
That points to an outdated or malformed free.html file on the embed host. Redeploy the latest embed file and verify it no longer contains literal replacement artifacts.
The widget requests localhost data in production. What should I check?
Verify the built widget bundle uses the production API base URL and that the server copied the latest dist assets to the static widget path.