Site Settings Tutorial

How to create a new site

To create a new site, you need to send a request to the Creating a site endpoint.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -L 
  --request POST 
  --url 'https://api.emporix.io/site/{tenant}/sites' 
  --header 'Content-Type: application/json' 
  --data '{
    "code": "example",
    "name": "ExampleName",
    "active": false,
    "default": false,
    "defaultLanguage": "en",
    "languages": [
      "en"
    ],
    "currency": "GBP",
    "homeBase": {
      "address": {
        "country": "GB",
        "zipCode": "12345"
      }
    },
    "shipToCountries": [
      "GB"
    ],
    "mixins": {},
    "metadata": {}
  }'

How to set a list of countries to which a site ships products

Countries that a site ships products to are stored as ISO 3166-1 alpha-2 codes in the shipToCountries list.

To update the shipToCountries list, you need to send a request to the Partially updating a site endpoint.

API Reference

curl -L \
  --request PATCH 
  --url 'https://api.emporix.io/site/{tenant}/sites/{siteCode}' 
  --header 'Content-Type: application/json' 
  --data '{
    "defaultLanguage": "en"
    "shipToCountries": [
      "AT",
      "CH",
      "DE"
    ]
  }'

How to enable payment methods

Payment methods are configured per site. Emporix Commerce Engine supports the following payment methods:

• Cash

• Credit card

• Direct debit

• Invoice

Information on whether specific payment methods are enabled or disabled is stored in the form of boolean flags in the orderProcessSettings mixin. To enable a payment method, you need to set its flag to true.

First, check if the orderProcessSettings mixin has already been configured by sending a request to the Retrieving a site mixin endpoint.

API Reference

curl -L 
  --url 'https://api.emporix.io/site/{tenant}/sites/{siteCode}/mixins/{mixinName}' 
  --header 'Accept: */*'

If your site's orderProcessSettings have never been configured before or have been deleted, you will receive a 404 error in the response body.

In this case, to enable specific payment methods, you need to send a request to the Creating a site mixin endpoint and set desired flags to true.

API Reference

curl -L 
  --request POST 
  --url 'https://api.emporix.io/site/{tenant}/sites/{siteCode}/mixins' 
  --header 'Content-Type: application/json' 
  --data '{
    "testMixin": {
    "active": true,
    "metadata": {
      "schema": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/695388d813fd4242de135807_testMixin_v1.json"
    }
  },
  "orderProcessSettings": {
    "paymentSettings": {
      "paymentByInvoice": true,
      "paymentByDebit": true,
      "paymentByCash": true,
      "paymentByCredit": false
    },
    "metadata": {}
    }
  }'

If your site's orderProcessSettings have already been configured, you will receive them in the response body.

In this case, to enable specific payment methods, you need to send a request to the Partially updating a site mixin endpoint and set desired flags to true.

API Reference

curl -L 
  --request PATCH 
  --url 'https://api.emporix.io/site/{tenant}/sites/{siteCode}/mixins/{mixinName}' 
  --header 'Content-Type: application/json' 
  --data '{
    "active": true,
  "paymentSettings": {
    "paymentByInvoice": true,
    "paymentByDebit": true,
    "paymentByCash": true,
    "paymentByCredit": false
  }
}

How to set up direct debit payments

Before you start

Make sure you have already finished the How to enable payment methods tutorial.

Configure your business bank account information

Your business bank account information is stored in the merchantInfo mixin.

First, check if the merchantInfo mixin has already been configured by sending a request to the Retrieving a site mixin endpoint.

API Reference

curl -L 
  --url 'https://api.emporix.io/site/{tenant}/sites/{siteCode}/mixins/{mixinName}' 
  --header 'Accept: */*'

If your site's merchantInfo has never been configured before or has been deleted, you will receive a 404 error in the response body. In this case, to set up your business's bank account information, you need to send a request to the Creating a site mixin endpoint.

API Reference

curl -L 
  --request POST 
  --url 'https://api.emporix.io/site/{tenant}/sites/{siteCode}/mixins' 
  --header 'Content-Type: application/json' 
  --data '{
    "testMixin": {
    "active": true,
    "metadata": {
      "schema": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/695388d813fd4242de135807_testMixin_v1.json"
    }
  },
  "merchantInfo": {
    "merchantName": " ",
    "merchantId": " ",
    "merchantFinanceInfo": {
      "merchantSalesTaxId": " ",
      "merchantIban": " ",
      "merchantBic": " ",
      "sepaCreditorId": " "
    },
    "metadata": {
      "schema": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/merchantAddressMixin.v10"
    }
  }
}

If your site's merchantInfo has already been configured, you will receive it in the response body.

Check if all of the following fields are filled out with correct information:

• merchantName

• merchantId

• merchantFinanceInfo

If you need to update your merchantInfo, you need to send a request to the Partially updating a site mixin endpoint.

API Reference

curl -L 
  --request PATCH 
  --url 'https://api.emporix.io/site/{tenant}/sites/{siteCode}/mixins/{mixinName}' 
  --header 'Content-Type: application/json' 
  --data '{
    "active": true,
  "merchantName": " ",
  "merchantId": " ",
  "merchantFinanceInfo": {
    "merchantSalesTaxId": " ",
    "merchantIban": " ",
    "merchantBic": " ",
    "sepaCreditorId": " "
  }
}

Configure settings for direct debit payments

Settings for direct debit payments are stored in the debitSettings mixin. To configure them, you need to send a request to the Creating a site mixin endpoint with a set of standard values in the request body.

API Reference

curl -L 
  --request POST 
  --url 'https://api.emporix.io/site/{tenant}/sites/{siteCode}/mixins' 
  --header 'Content-Type: application/json' 
  --data '{
    "testMixin": {
    "active": true,
    "metadata": {
      "schema": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/695388d813fd4242de135807_testMixin_v1.json"
    }
  },
  "debitSettings": {
    "orderInformation": {
      "paymentMethod": "paymentByDebit",
      "status": "80",
      "postExportOrderStatus": "90"
    },
    "transactionType": {
      "serviceLevel": "SEPA",
      "sequenceType": "FRST",
      "debitArt": "COR1"
    },
    "debitInformation": {
      "paymentMethod": "DD",
      "batchBooking": true,
      "chargeBearer": "SLEV",
      "usage": "{merchantName}",
      "pmtInfId": "PMT-IDO-"
    },
    "metadata": {
      "schema": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/debitSettingsSiteMixIn.v3"
    }
  }
}

Specify your business's SEPA Creditor ID

Your business's SEPA Creditor ID is stored in your tenant's sepaCreditor configuration. To set up a sepaCreditor configuration, you need to send a request to the Creating configurations endpoint.

API Reference

curl -L 
  --request POST 
  --url 'https://api.emporix.io/configuration/{tenant}/configurations' 
  --header 'Content-Type: application/json' 
  --data '[
    {
      "key": "sepaCreditor",
      "secured": false,
      "value": "",
      "version": 1
    },
  ]'

How to add custom attributes to a site

Custom site attributes are stored in a site's mixins.

To learn more about mixins in the Emporix Commerce Engine, check out the Standard Practices in the Emporix API.

Define a JSON schema

To be able to apply mixins to your site's settings, you first need to define your custom attributes in the form of a JSON schema.

{
  "name": "customerSettings",
  "description": "Mixin schema for site-specific customer settings.",
  "properties": {
    "regExSettings": {
      "type": "object",
      "description": "Regular expressions for input validation.",
      "properties": {
        "bic": {
          "type": "string"
        },
        "mail": {
          "type": "string"
        },
        "accountOwner": {
          "type": "string"
        },
        "phone": {
          "type": "string"
        },
        "password": {
          "type": "string"
        }
      }
    }
  },
  "type": "object",
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Next, upload your schema to a hosting service and save its URL.

Apply custom attributes to a site

Once your schema is ready, send a request to the Creating a site mixin endpoint with the site's custom attributes in the request body.

API Reference

curl -L 
  --request POST 
  --url 'https://api.emporix.io/site/{tenant}/sites/{siteCode}/mixins' 
  --header 'Content-Type: application/json' 
    "testMixin": {
    "active": true,
    "metadata": {
      "schema": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/695388d813fd4242de135807_testMixin_v1.json"
    }
  },
  "customerSettings": {
    "regExSettings": {
      "mail": "^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\.[a-zA-Z0-9-.]+$",
      "phone": "^[0-9\\+][0-9]{7,}$",
      "password": ".{6,}",
      "bic": "^((.{8})|(.{11}))$",
      "accountOwner": "^[a-zA-Z0-9''':?,()\\-. +/ÄäÜüÖöß&]{0,70}$"
    },
    "metadata": {
      "schema": "{schemaURL}"
    }
  }
}'

Add or modify mixins when updating a site

You can also add or modify mixins when partially updating a site by sending a request to the Partially updating a site endpoint. This approach allows you to update both the mixin schema reference in metadata.mixins and the mixin data in mixins in a single request.

API Reference

curl -L 
  --request PATCH 
  --url 'https://api.emporix.io/site/{tenant}/sites/{siteCode}' 
  --header 'Content-Type: application/json' 
  --data '{
    "metadata": {
      "mixins": {
        "exampleMixin": "https://res.cloudinary.com/saas-ag/raw/upload/v1764338354/emporix-docs/test3_v1.json"
      }
    },
    "mixins": {
      "exampleMixin": {
        "field3": "value3"
      }
    }
  }'