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 identifier

• secured — 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": "client_key_identifier",
  "client": "client_name",
  "key": "configuration_key",
  "value": "configuration_value"
}

• _id — Unique identifier combining client and key

• client — The client/service name

• key — The configuration key identifier

• value — 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:

Configuration Key	Description
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.

API Reference

curl -L 
  --url 'https://api.emporix.io/configuration/{tenant}/configurations' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Accept: */*'

You can also filter configurations by specific keys using the keys query parameter, for example:

curl -L 
  --url 'https://api.emporix.io/configuration/{tenant}/configurations?keys=project_lang' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Accept: */*'

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.

API Reference

curl -L 
  --url 'https://api.emporix.io/configuration/{tenant}/configurations/{propertyKey}' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Accept: */*'

Example: Retrieving the language configuration

curl -L 
  --url 'https://api.emporix.io/configuration/{tenant}/configurations/project_lang' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Accept: */*'

The example response looks like:

{
  "key": "project_lang",
  "secured": false,
  "value": "[{\"id\":\"en\",\"label\":\"English\",\"default\":true,\"required\":true}]",
  "version": 2
}

How to create tenant configurations

To create new tenant configurations, send a request to the Creating configurations endpoint.

API Reference

Example: Creating multiple configurations at once

curl -L 
  --request POST 
  --url 'https://api.emporix.io/configuration/{tenant}/configurations' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Content-Type: application/json' 
  --data '[
    {
      "key": "project_country",
      "secured": false,
      "value": "DE",
      "version": 1
    },
    {
      "key": "project_lang",
      "secured": false,
      "value": "[{\"id\":\"en\",\"label\":\"English\",\"default\":true,\"required\":true},{\"id\":\"de\",\"label\":\"German\",\"default\":false,\"required\":false}]",
      "version": 1
    }
  ]'

Example: Creating invoice settings configuration

curl -L 
  --request POST 
  --url 'https://api.emporix.io/configuration/{tenant}/configurations' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Content-Type: application/json' 
  --data '[
    {
      "key": "invoiceSettings",
      "secured": false,
      "value": {
        "threshold": "24",
        "status": "CREATED,CONFIRMED",
        "extendedOrderStatus": "70,75,76"
      },
      "version": 1
    }
  ]'

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.

API Reference

Example: Updating the country configuration

curl -L 
  --request PUT 
  --url 'https://api.emporix.io/configuration/{tenant}/configurations/project_country' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Content-Type: application/json' 
  --data '{
    "key": "project_country",
    "secured": false,
    "value": "AT",
    "version": 1
  }'

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

curl -L 
  --request PUT 
  --url 'https://api.emporix.io/configuration/{tenant}/configurations/customer.deletion.redirecturl' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Content-Type: application/json' 
  --data '{
    "key": "customer.deletion.redirecturl",
    "secured": false,
    "value": "https://tenant.com/custDelete?token=",
    "version": 1
  }'

Example: Updating tax configuration

curl -L 
  --request PUT 
  --url 'https://api.emporix.io/configuration/{tenant}/configurations/taxConfiguration' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Content-Type: application/json' 
  --data '{
    "key": "taxConfiguration",
    "secured": false,
    "value": {
      "taxClassOrder": ["FULL", "HALF", "ZERO"],
      "taxClasses": {
        "FULL": 19,
        "HALF": 7,
        "ZERO": 0
      }
    },
    "version": 1
  }'

Example: Updating packaging configuration

curl -L 
  --request PUT 
  --url 'https://api.emporix.io/configuration/{tenant}/configurations/packagingConf' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Content-Type: application/json' 
  --data '{
    "key": "packagingConf",
    "secured": false,
    "value": {
      "packagingGroupOptions": [
        "1_cooling_product",
        "2_standard",
        "3_fragile"
      ],
      "packagingPositionOptions": [
        "1_bottom_robust",
        "2_bottom_insensitive",
        "3_middle_standard",
        "4_top_sensitive"
      ]
    },
    "version": 1
  }'

Example: Updating storefront settings

curl -L 
  --request PUT 
  --url 'https://api.emporix.io/configuration/{tenant}/configurations/storefront.host' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Content-Type: application/json' 
  --data '{
    "key": "storefront.host",
    "secured": false,
    "value": "tenant.com",
    "version": 1
  }'

Example: Updating email notification settings

curl -L 
  --request PUT 
  --url 'https://api.emporix.io/configuration/{tenant}/configurations/cust.notification.email.from' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Content-Type: application/json' 
  --data '{
    "key": "cust.notification.email.from",
    "secured": false,
    "value": "[email protected]",
    "version": 1
  }'

How to delete a tenant configuration

To delete a tenant configuration, send a request to the Deleting a configuration endpoint.

API Reference

curl -L 
  --request DELETE 
  --url 'https://api.emporix.io/configuration/{tenant}/configurations/{propertyKey}' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN'

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.

API Reference

curl -L 
  --url 'https://api.emporix.io/configuration/{tenant}/clients' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Accept: */*'

The example response looks like:

[
  "saas-ag.caas-indexing-service-client"
]

How to retrieve client configurations

To retrieve all configurations for a specific client, send a request to the Retrieving client configurations endpoint.

API Reference

curl -L 
  --url 'https://api.emporix.io/configuration/{tenant}/clients/{client}/configurations' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Accept: */*'

Example: Retrieving indexing service client configurations

curl -L 
  --url 'https://api.emporix.io/configuration/{tenant}/clients/saas-ag.caas-indexing-service-client/configurations' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Accept: */*'

The example response looks like:

[
  {
    "_id": "saas-ag.caas-indexing-service-client_algolia_activation",
    "client": "saas-ag.caas-indexing-service-client",
    "key": "algolia_activation",
    "value": true
  },
  {
    "_id": "saas-ag.caas-indexing-service-client_indexing_configuration",
    "client": "saas-ag.caas-indexing-service-client",
    "key": "indexing_configuration",
    "value": {
      "activePublishedProductIndexing": true,
      "activeNonPublishedProductIndexing": true
    }
  }
]

You can also filter client configurations by specific keys using the keys query parameter:

curl -L 
  --url 'https://api.emporix.io/configuration/{tenant}/clients/{client}/configurations?keys=algolia_activation' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Accept: */*'

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.

API Reference

curl -L 
  --url 'https://api.emporix.io/configuration/{tenant}/clients/{client}/configurations/{propertyKey}' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Accept: */*'

Example: Retrieving a specific indexing configuration

curl -L 
  --url 'https://api.emporix.io/configuration/{tenant}/clients/saas-ag.caas-indexing-service-client/configurations/indexing_configuration' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Accept: */*'

The example response looks like:

{
  "_id": "saas-ag.caas-indexing-service-client_indexing_configuration",
  "client": "saas-ag.caas-indexing-service-client",
  "key": "indexing_configuration",
  "value": {
    "activePublishedProductIndexing": true,
    "activeNonPublishedProductIndexing": true
  }
}

How to create client configurations

To create new client configurations, send a request to the Creating client configurations endpoint.

API Reference

curl -L 
  --request POST 
  --url 'https://api.emporix.io/configuration/{tenant}/clients/{client}/configurations' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Content-Type: application/json' 
  --data '[
    {
      "client": "test_client",
      "key": "test_key",
      "value": true
    }
  ]'

Example: Creating a client configuration

curl -L 
  --request POST 
  --url 'https://api.emporix.io/configuration/{tenant}/clients/client_one/configurations' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Content-Type: application/json' 
  --data '[
    {
      "client": "example_client",
      "key": "example_key",
      "value": true
    }
  ]'

The response looks like:

{
  "_id": "client_one_example_key",
  "client": "client_one",
  "key": "example_key",
  "value": true,
  "description": null,
  "schemaUrl": null,
  "version": 0,
  "secured": false,
  "restricted": false,
  "readOnly": false
}

How to update a client configuration

To update an existing client configuration, send a request to the Updating a client configuration endpoint.

API Reference

curl -L 
  --request PUT 
  --url 'https://api.emporix.io/configuration/{tenant}/clients/{client}/configurations/{propertyKey}' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Content-Type: application/json' 
  --data '{
    "client": "example_client",
    "key": "example_key",
    "value": false
  }'

How to delete a client configuration

To delete a client configuration, send a request to the Deleting a client configuration endpoint.

API Reference

curl -L 
  --request DELETE 
  --url 'https://api.emporix.io/configuration/{tenant}/clients/{client}/configurations/{propertyKey}' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN'

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.

API Reference

curl -L 
  --url 'https://api.emporix.io/configuration/{tenant}/global-configurations' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Accept: */*'

You can also filter global configurations by specific keys using the keys query parameter:

curl -L 
  --url 'https://api.emporix.io/configuration/{tenant}/global-configurations?keys=project_lang,project_curr' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Accept: */*'

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.