Configure Vertex in the Back Office

This document describes how to manage Vertex settings from Back Office > Configuration and how to select the tax provider per scope store.

With this feature enabled, operators manage every Vertex setting from the Back Office, per global or store scope, instead of environment variables. A new Configuration > Taxes > Tax Provider switch chooses between the built-in Spryker tax calculation and Vertex. Save-time validation prevents leaving the integration in a broken state.

Prerequisites

• Use spryker-eco/vertex version 1.5.0 or later.
• Integrate Vertex into your Spryker shop.
• Install the Configuration Management feature. The Vertex module depends on spryker/configuration-extension, but it does not require the spryker/configuration module that provides the Back Office UI and stores the values. If the Configuration Management feature is not installed yet, install it first. For details, see Install the Configuration Management feature.

1. Enable the configuration source

The configuration source is gated behind the isConfigurationModuleUsed() flag, which defaults to false (environment-based behavior). To read values from the Back Office instead, override the flag in src/Pyz/Shared/Vertex/VertexConfig.php to return true:

<?php

namespace Pyz\Shared\Vertex;

use SprykerEco\Shared\Vertex\VertexConfig as SprykerEcoVertexConfig;

class VertexConfig extends SprykerEcoVertexConfig
{
    public function isConfigurationModuleUsed(): bool
    {
        return true;
    }
}

When the flag is true, SprykerEco\Zed\Vertex\VertexConfig reads values using getModuleConfig instead of from the config/Shared/config_default.php constants.

2. Register the pre-save validation plugin

Register VertexTaxProviderPreSavePlugin in src/Pyz/Zed/Configuration/ConfigurationDependencyProvider.php to enable save-time validation:

<?php

namespace Pyz\Zed\Configuration;

use Spryker\Zed\Configuration\ConfigurationDependencyProvider as SprykerConfigurationDependencyProvider;
use SprykerEco\Zed\Vertex\Communication\Plugin\Configuration\VertexTaxProviderPreSavePlugin;

class ConfigurationDependencyProvider extends SprykerConfigurationDependencyProvider
{
    /**
     * @return array<\Spryker\Zed\ConfigurationExtension\Dependency\Plugin\ConfigurationValuePreSavePluginInterface>
     */
    protected function getConfigurationValuePreSavePlugins(): array
    {
        return [
            // ... other plugins
            new VertexTaxProviderPreSavePlugin(),
        ];
    }
}

3. Sync the configuration schema

Sync the configuration schema so the Vertex settings appear in the Back Office:

console configuration:sync

4. Manage Vertex settings in the Back Office

After the sync, the settings are available under Configuration in Integrations > Vertex. All settings are scoped to global and store by default.

Integrations > Vertex

Taxes > Tax Provider

Selecting vertex requires a complete Vertex configuration for that scope. This requirement is enforced at save time.

Configuration source and precedence

The active configuration source depends on the flag Spryker\Shared\Vertex\VertexConfig::isConfigurationModuleUsed() or its project-level value:

• Flag off (default): getters read the legacy VERTEX:* environment values from config/Shared/config_default.php.
• Flag on: getters resolve values per scope store from the spryker/configuration. Environment values from config/Shared/config_default.php is ignored.

Save-time validation

When you save a configuration, the following changes are blocked to prevent leaving the integration in a broken state:

1. Selecting Vertex while incomplete: you cannot switch the tax provider to Vertex if Vertex is not fully configured for that scope. The error lists the missing fields.
2. Breaking an active configuration: you cannot clear or remove a credential that would leave Vertex incomplete while Vertex is the selected provider for that scope. This applies to both edits and deletions.
3. Cross-scope breakage: a change to the global scope that would break any store that has Vertex selected and inherits the global values is blocked. The error names the affected store.
4. Invalid URLs: the Security URI, Transaction calls URI, and Taxamo API URL must be valid URLs, even when Vertex is not the selected provider.

Next steps

Verify Vertex connection