--- title: 'Functionality, Configuration, and External Services | Shopware Community Hub' description: >- Learn how to design Store extension functionality, configuration, external API handling, sales-channel scope, and service disclosures clearly. canonical_url: >- https://hub.shopware.comhttps://hub.shopware.com/learn/unit/functionality-configuration-and-external-services --- # Functionality, Configuration, and External Services - Integrate external APIs in a user-friendly and traceable way. - Design configuration and status messages so merchants can work confidently. - Consider sales-channel-specific requirements consciously. - Disclose external services transparently in the Store listing. - Identify business models with external fees or transactions early. # Functionality, Configuration, and External Services An extension can be technically correct and still be hard for merchants to use. If configuration is unclear, external services fail silently, or sales-channel behavior is surprising, the extension does not feel reliable. Store-ready functionality is therefore not only about what the extension can do. It is also about how clearly merchants can configure it, test it, understand its status, and see which external services are involved. In this unit, you will learn how to design functionality and configuration so that the extension is easier to review, easier to operate, and easier to trust. ## Configuration Should Help Merchants Work Confidently Configuration is part of the merchant experience. A merchant should be able to understand what the extension needs, what each setting affects, and whether the current setup is valid. The functionality and integration documentation describes several expectations for Store extensions. The core idea is that extensions should integrate cleanly with Shopware and provide clear feedback when they depend on configuration or external systems. Good configuration helps merchants answer questions such as: - What do I need to enter before the extension works? - Is my current configuration valid? - Does this setting apply globally or only to a specific sales channel? - What happens if an external service is unavailable? - Where can I find errors when something does not work? The important mental model is this: > A merchant should not need to guess whether an extension is configured correctly. The extension should make its state visible. ## External APIs Need Testable Connections Many extensions connect to external systems such as ERP, CRM, payment, marketing, shipping, analytics, or search services. When an extension needs external API credentials, partners should provide a clear way to test or validate them. We recommend an API test button or validation when credentials are saved. This is important because invalid credentials are one of the most common setup problems. Without clear validation, the merchant may only discover the problem later, for example when an order synchronization fails or a checkout process cannot continue. A good external API integration should: - validate credentials when possible - provide an API test button or comparable test flow - show a clear success or failure message in the administration - log errors in a useful place, such as `/var/log/` or the database event log - avoid exposing sensitive credentials in logs or messages This does not mean the UI needs to be complex. It means the merchant needs enough feedback to know whether the connection works. ## Status Messages and Logs Need to Tell the Same Story Status messages and logs serve different audiences. Status messages help merchants understand what happened. Logs help partners and technical teams investigate why it happened. For example, if an API connection fails, the merchant-facing message might say: > The API connection could not be verified. Please check the credentials and try again. The log can contain more technical context, such as the endpoint, response status, or error category. It should still avoid sensitive data such as full access tokens or passwords. This split matters because a merchant does not need a stack trace in the administration. But support needs enough traceability to investigate the issue quickly. ## Sales-Channel Scope Must Be Clear Extensions visible in the storefront must either be configurable per sales channel or clearly limited to one sales channel. This matters because merchants often operate multiple sales channels with different languages, currencies, domains, themes, or business rules. A setting that is correct for one storefront may be wrong for another. For partners, this means sales-channel scope should be planned early: - Does the extension appear in the storefront? - Can the behavior differ per sales channel? - Does the extension use `config.xml`? - Are settings clearly scoped or intentionally global? - Can merchants understand where a setting applies? For apps, the documentation explicitly notes that apps visible in the storefront with `config.xml` must support separate configuration per sales channel. The goal is not to make every setting per-sales-channel by default. The goal is to avoid unclear behavior. If a setting is global, that should be intentional and understandable. ## External Services Must Be Disclosed If an extension uses external fonts or external services, this must be included in the Store listing. Examples can include: - Google Fonts - Font Awesome - analytics services - marketing or tracking services - third-party API platforms - external payment, shipping, or tax services This is not only a Store listing detail. It affects merchant expectations, privacy review, legal review, and operational planning. Merchants need to know whether an extension depends on external services before they install it. They may need to check data protection requirements, contracts, availability, costs, or internal security rules. ## External Fees and Technology Partner Relevance Some extensions are not only technical integrations. They can also include downstream costs, transaction fees, service fees, or commission-based business models. Some extensions may also require a Shopware technology agreement. This applies particularly to software extensions or interfaces that involve downstream costs, transaction fees, or service fees for the customer. For partners, this means the business model should be checked early. It should not be discovered only shortly before publishing. Before submitting an extension, ask: - Does the extension connect to a paid external service? - Does the merchant need a separate contract or account? - Are there transaction-based costs? - Are service fees or downstream costs involved? - Does this require additional agreement or review before activation? If the answer is yes, this should be reflected in the Store listing and discussed with the relevant Shopware contact early. ## Example: Integrating an External Shipping Service Imagine a partner builds an extension that connects Shopware to an external shipping service. The extension needs API credentials, displays shipping-related information in the storefront, and may behave differently per sales channel. A review-ready implementation should not only send API requests. It should also: - validate the credentials when they are saved - offer a clear connection test - show whether the external service is reachable - log failed responses without exposing secrets - let merchants configure the behavior per sales channel if needed - explain in the Store listing that an external shipping service is used - disclose any additional fees or account requirements This makes the extension easier to operate. It also makes the Store Review easier, because the integration behavior is visible and traceable. ## Common Pitfalls ### Letting External API Failures Stay Invisible If an external service fails silently, merchants cannot know whether the issue is configuration, connectivity, credentials, or extension behavior. ### Using One Global Setting for Every Sales Channel Global settings can be valid, but they become risky when the extension appears in multiple storefronts with different requirements. ### Showing Technical Errors Directly to Merchants Status messages should be understandable. Technical details belong in logs, not in confusing merchant-facing messages. ### Forgetting External Service Disclosure External fonts, APIs, or services must be transparent in the Store listing. Hidden dependencies can create legal, privacy, or operational issues for merchants. ## Summary - External APIs should be testable or validated when credentials are saved. - Merchants need clear status messages in the administration. - Technical errors should be logged in a useful and secure way. - Storefront-visible extensions need clear sales-channel scope. - External fonts, services, fees, and transaction-based business models should be disclosed early and reflected in the Store listing. Next, you will look at storefront behavior, performance, and error-free operation so that the extension also behaves reliably for customers.