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. Many of these keys (although not all) can also be managed in Management Dashboard -> Settings -> System Preferences. The MD Setting column indicates whether a key is available there. For full descriptions, possible values, and default values of keys marked yes, see System Preferences.
allowAnonymousCheckoutWithExistingCustomerEmail
Whether anonymous checkout is allowed when the customer email already exists
yes
allowToSkipRelatedProductsValidation
Whether related products validation can be skipped
yes
approval.default_expiryDays
Default number of days until an approval expires
yes
approval.enableQuoteApprovalProcess
Whether the quote approval workflow is enabled
yes
cartItemValidationSkipCurrency
Whether currency is optional when adding items to cart
yes
cartItemValidationSkipEffectiveAmount
Whether effectiveAmount is optional when adding items to cart
yes
cartItemValidationSkipExistingItemsValidationOnAddToCart
Whether to skip validation for existing cart items when adding a new item
yes
cartItemValidationSkipOriginalAmount
Whether originalAmount is optional when adding items to cart
yes
companyContactPropagation
How company contact assignments are propagated in a company hierarchy (DOWNWARD, UPWARD, or DISABLED)
yes
couponPermanentDelete
Whether deleted coupons are permanently removed from the database instead of being flagged as deleted
yes
cust.notification.email.from
Email address used as the sender for customer notifications
no
customer.changeemail.redirecturl
URL to redirect customers when changing their email address
no
customer.deletion.redirecturl
URL to redirect customers after account deletion
no
customer.passwordreset.redirecturl
URL of the page for resetting the customer's password
yes
customerActiveOnCreation
Whether newly created customers are set as active by default
yes
customerOnHoldOnCreation
Whether newly created customers are set on hold by default
yes
enableCouponCodeCaseSensitivity
Whether coupon codes can be saved in both upper and lower case
yes
enableExternalPrices
Whether external price and product sourcing is enabled at cart level
yes
enableLegalEntityAddressFallbackInCart
Whether to fall back to the legal entity address in cart when no address is provided
yes
enableOrderAddressPropagation
Whether the address from an order is automatically saved to the customer profile
yes
enableProductCategoryAssignmentValidation
Whether to validate that a product exists before assigning it to a category
yes
enableRecreationOfDeletedCustomer
Whether a customer with the same customer number can be created after deletion
no
enableSyncBetweenRestrictionsAndSiteCodes
Whether entity restrictions are synchronized with defined site codes
yes
invoiceSettings
Invoice generation thresholds and statuses
no
maxNumberOfCouponsPerCart
Maximum number of coupons that can be applied per cart
yes
openAiApiToken
OpenAI API token used to connect Emporix AI features to OpenAI
yes
packagingConf
Packaging groups and position options
no
populateProductDetailsOnAddToCart
Whether product details are automatically populated when adding items to cart
yes
project_country
Default country for your tenant
no
project_curr
Default currencies for your tenant
no
project_lang
Default languages for your tenant
no
restrictions
List of restrictions applied to site-aware entities
yes
signUp.enableAccountCreationEmailConfirmation
Whether welcome emails are sent when new customer accounts are created
yes
ssoCustomerAutoprovisioningDisabled
Whether automatic customer creation during SSO token exchange is disabled
yes
ssoCustomerIdentifierField
Field used to identify customers during token exchange (EMAIL or SUBJECT)
yes
storefront.host
Hostname for your storefront
no
storefront.htmlPage
Default HTML page for your storefront
no
taxConfiguration
Tax classes and rates configuration
no
unitConf
Unit conversion configurations
no
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
Example: Enabling recreation of deleted customers
Enabling recreation of deleted customers
By default, for security reasons, it is not possible to recreate a customer that was previously deleted. During customer creation, the Customer Service rejects requests that use a customerNumber already assigned to a deleted customer profile.
To allow recreation of previously deleted customers with the same customer number, create the enableRecreationOfDeletedCustomer tenant configuration and set its value to true, as shown in the preceding example.
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?