Configuration Service Tutorial
The Configuration Service is a general store for tenant-specific information. It allows you to manage various settings and configurations that control how your Emporix e-commerce system operates.
Types of configurations
The Configuration Service manages three types of configurations:
Tenant configurations — Applicable to all services across the tenant. Use tenant configurations for settings that apply across your entire tenant, such as:
Default languages, currencies, and countries
Customer redirect URLs
Email notification settings
Tax and packaging configurations
Storefront settings
Client configurations — Associated with particular services. Use client configurations for service-specific settings, such as indexing configurations.
Global configurations — Read-only configurations associated with all services across all tenants.
Configuration structure
Tenant configurations:
{
"key": "configuration_key",
"secured": false,
"value": "configuration_value",
"version": 1
}key— The configuration key identifiersecured— Whether the configuration is secured (boolean)value— The configuration value (can be a string, number, boolean, object, or array)version— The version number of the configuration (incremented on each update)
Client configurations:
_id— Unique identifier combining client and keyclient— The client/service namekey— The configuration key identifiervalue— The configuration value (can be a string, number, boolean, object, or array)
Common configuration keys
The Configuration Service supports various configuration keys for different purposes:
customer.passwordreset.redirecturl
URL to redirect customers when resetting their password
customer.changeemail.redirecturl
URL to redirect customers when changing their email address
cust.notification.email.from
Email address used as the sender for customer notifications
customer.deletion.redirecturl
URL to redirect customers after account deletion
project_country
Default country for your tenant
project_curr
Default currencies for your tenant
project_lang
Default languages for your tenant
taxConfiguration
Tax classes and rates configuration
packagingConf
Packaging groups and position options
storefront.host
Hostname for your storefront
storefront.htmlPage
Default HTML page for your storefront
unitConf
Unit conversion configurations
invoiceSettings
Invoice generation thresholds and statuses
Managing tenant configurations
How to retrieve all tenant configurations
To retrieve a list of all tenant configurations, send a request to the Retrieving configurations endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
You can also filter configurations by specific keys using the keys query parameter, for example:
How to retrieve a specific tenant configuration
To retrieve a specific tenant configuration by its key, send a request to the Retrieving a configuration endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
Example: Retrieving the language configuration
The example response looks like:
How to create tenant configurations
To create new tenant configurations, send a request to the Creating configurations endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
Example: Creating multiple configurations at once
Example: Creating invoice settings configuration
When creating configurations, make sure the version field is set to 1 for new configurations. The version number is incremented automatically when you update the configuration.
How to update a tenant configuration
To update an existing tenant configuration, send a request to the Updating a configuration endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
Example: Updating the country configuration
The key in the request body must match the propertyKey in the URL path. Also, make sure to include the current version number from the existing configuration to avoid conflicts.
Example: Updating customer redirect URLs
Example: Updating tax configuration
Example: Updating packaging configuration
Example: Updating storefront settings
Example: Updating email notification settings
How to delete a tenant configuration
To delete a tenant configuration, send a request to the Deleting a configuration endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
Managing client configurations
Client configurations are service-specific settings that apply to particular services rather than the entire tenant.
How to retrieve available clients
To retrieve a list of available clients for your tenant, send a request to the Retrieving clients endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
The example response looks like:
How to retrieve client configurations
To retrieve all configurations for a specific client, send a request to the Retrieving client configurations endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
Example: Retrieving indexing service client configurations
The example response looks like:
You can also filter client configurations by specific keys using the keys query parameter:
How to retrieve a specific client configuration
To retrieve a specific client configuration by its key, send a request to the Retrieving a client configuration endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
Example: Retrieving a specific indexing configuration
The example response looks like:
How to create client configurations
To create new client configurations, send a request to the Creating client configurations endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
Example: Creating a client configuration
The response looks like:
How to update a client configuration
To update an existing client configuration, send a request to the Updating a client configuration endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
How to delete a client configuration
To delete a client configuration, send a request to the Deleting a client configuration endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
Retrieving global configurations
Global configurations are read-only configurations that are associated with all services across all tenants. These configurations provide default values and system-wide settings.
How to retrieve global configurations
To retrieve a list of global configurations, send a request to the Retrieving global configurations endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
You can also filter global configurations by specific keys using the keys query parameter:
Global configurations are read-only and cannot be created, updated, or deleted through the API. They are managed by the Emporix system and provide default values that can be overridden by tenant configurations.
Last updated
Was this helpful?