Mercury:Manual

Access Website

Access Your Shop

After your shop is ready, you'll get three addresses (URLs): the server address, the management address, and a main address.

The server address refers to the server of your shop, you only need it in some special cases (e.g. Prometheus entry point).

The management address is the address that you can use to access the management panel, where you can maintain your shop.

The main address is the entrance for your customers. In most cases, you want to replace the default main address later with your own address. It's not recommended for most shops but you may have multiple main addresses at the same time.

Manage Your Contract (Subscription)

You can login to our official website to manage your contract (subscription) using one of the following ways.

• Visit https://www.esoul.online and search for your contract in user center.
• Login to your management panel and use Help & Support / Manage Subscription to redirect to the related contract directly.

In the subscription overview page, you can change your tariffs or payment method, cancel subscription, or book additional services like domains.

Login / Logout / Access to the Management Panel

The built-in administrator account password will be sent to your email when your shop is ready. It's an one-time password. You can login with your email address and the password. You can create other administrator accounts via Information & System / Account after that.

It's always required that you (and all other administrators) check the computer and network environment before login. Login from an insecure computer / network may cause security issues.

If you save your password, you don't need to login again within about 30 days, as long as you use the same browser and don't change your IP address. If your IP address changes, you have to login again.

You can logout anytime via your account menu on the top right of the screen. You can also change your password here.

Please remember your password carefully. Due to security reason, it's not allowed to reset your password via email. If you shop has multiple administrators, you may reset your password via other accounts with required permission. Otherwise, you have to contact eSoul team and reset your password via customer service.

Your password expires every 90 days unless the password never expires permission is granted. You can still login with expired password. However, most of the features are disabled in this case. You need to modify your password to reactivate these features.

Warning in Browser Caches

It's notable that some information are cached as long as your browser is open. You may want to close the browser to clear all the information. Mercury set the cache-control header to guide your browser to manage the cache, so that no sensible information are saved unintendedly. However, we can't guarantee that your browser follow the guide. Depending on the settings of your browser, some caches may still exist even after you close your browser. You need to read the manual of your browser and clear the cache if needed. This may be required by your local law.

Change Password

You can change your own password via your account menu. The password length should in the range of 8 - 32 characters.

It's very important to avoid simple passwords like "12345678", or "aaaaaaaa".

Please also check other sessions of this chapter to get more information about your password.

View Operation History

You can view all of your operations in the past 7 days via your account menu.

It's notable that your operation histories won't be removed after 7 days. They still exist in the whole site logs and can be checked by the you or other administrators with proper permission.

Website Management

Logs

You can view the site logs in Information & System / Logs. It includes all the changes of your site in the past 90 days. Older logs will be removed automatically.

Identifiers

By default, the ID of many types of data is starting from 1 (e.g. administrator ID, article ID, user ID) and increase by 1 when a new data is generated. Sometimes, it's easier to maintain IDs with fixed length. You may manually adjust the next ID of many types of data via Information & System / Identifiers. For example if you set the next ID of administrator to 1001, the next created administrator will have the ID 1001, and the one after next will have the ID 1002, etc.

The specified ID must be larger than the ID of any existing data of the same type.

Accounts & Groups of Administrator

Overview

You can manage the accounts and groups of administrator via Information & System / Administrator and Information & System / Group. An administrator can login using it's account, their right is defined by the belonging groups in general.

To make it clear, we use account to describe the credential and administrator to describe the person in this section.

Please also read Mercury:Manual#Access Website for more information.

Right

A group is a non-exclusive collection of of accounts. It means an account may belong to from 0 to any groups.

In general, the right to view specific data / perform specific jobs can be granted to each group. The administrator is allowed when its account is in any group with the related right. Please take care that we only have a so-called white-list-algorithm. You can't ban / black-list an administrator. The only way to disallow an administrator from view specific data / perform specific jobs is to make sure that its account is not in any group allowing this.

The granted right is updated automatically, whenever the right of a group is updated, the right of all it's members is updated too. You don't have to move any account out and in to apply the change.

You can also grant right directly to an administrator without using group. However, it's not recommended since it significantly increases the complexity managing the accounts.

Password Management

You may change the password of any account, however it's recommended that each administrator manages it's own account including the password. Sometimes, you may want to give the right "password never expires" to an account. You should limit the right of such accounts to avoid any risk.

3rd-Party Accounts

The 3rd-party accounts are maintained centrally via Information & System / Third-Party Accounts. These accounts are shared to the plugins to provide more features. Each account has a configuration in JSON format. In general, you should avoid to have multiple accounts of the same type to avoid unexpected behaviors. Some plugins work with multiple accounts. Please read the documents of plugins for more details.

Mercury counts the number of calls of each account. Please note that this count is for reference only, as there may be some discrepancy from the actual count due to technical reasons.

Email Draft

A draft is a template generating emails. There’re different types of draft for different usages, e.g. order confirmation, reset password. You can manage the draft Information & System / Email Draft. Below is a list of currently supported types.

Internal Name	Name	Description	Attachments
system.default	general email	general email to user	-
mercury.pass	voucher delivery	delivery a voucher via email	voucher in PDF format

You may use variables in the title and body, depending on the type, e.g. %SITENAME% in the title or body will be replaced by the name of the site. Please read the list below for details.

Name	Description	Types
%SITENAME%	name of the site	all
%SITEEMAIL%	email address of the site	all

Shop Setup

Level

By default, the website frontend will display all articles in descending order by display level. The minimum display level is 1. You can manage log levels via Article & Catalog / Level.

Shop Management

Order & Subscription

In general, the orders are submitted by the user. It's allowed for administrators to submit an order from the management panel in a similar way. It's often considered for example for submission via telephone.

There are some general limitations apply to each order.

An order can have two addresses, one invoice address, one delivery adddress. If there's no delivery address specified, then the invoice address is considered as delivery address.

An order has a start

Service Start & End

Each order has a service start time and a service end time. Depending on the article you sell, it may or may not leading to some scenes. By default, the service start time and end time are both equal to the order time. You can change it as required.

By default, it's hidden to the customer. You can make it visible if needed. Please read the article management for more details.

Subscription

Subscription is a way to generate new orders periodically and automatically. In this way, you and your customer can maintain a series of orders covering a long service time period. The service start time and the service end time of the orders is calculated automatically.

You can edit the subscription and it's elements in a similar way as the regular orders. However, you can't apply coupons to a subscription. If you want to give a permanent discount to the subscription, you should add a customized element with a negative price.

You can also add a long-term payment to the subscription, whenever an order is created from the subscription, the payment is also created.

The time period of a subscription can be specified in days or months. You can obviously specify for example "28 days" for 4 weeks or "12 months" for a year. There's a setting called "Create Order from Subscription X Days before Start". As the name says, the order will be created X days before the start of the new time period.

The subscription itself also has a property service start time and service end time like the orders. It is used to validate the subscription. A new order will be created if and only if the service start time of the order is located within the service time period of the subscription. Obviously you can also set a subscription without end time so that it will work endlessly unless stopped manually.

For example a subscription of 2 years (24 months) starting from 01/01/2020 to 12/31/2021 with 2 months time period will generates 12 orders, the first order refers to the service from 01/01/2020 to 02/28/2020 and the last refers to the service from 01/11/2021 to 31/12/2021. If the orders will be created 14 days before start, then the customer will receive the notification of the last order around 17/10/2021.

For digital article selling, the meta information of the subscription will be inherited by the order.

Coupon

A coupon is an one-time random code, which is often used as discount code in digital or printed form. A user can apply the code by entering it in the order process to get the specified discount (see detailed description below).

Each code has it's own start time and end time (expiration time). A user can only apply a code in this time interval.

Mercury allows to apply multiple coupons (no matter if they're in the same group or not) unless a coupon is declared as exclusive. You can limit the total discount of multiple coupons with coupon permissions, which is described later.

To create a coupon, you have to create a coupon group at first, which contains codes with same settings (name, amount, etc.). Then you can add codes to the group. There's an export function allowing you to export multiple codes to CSV table.

Please protect the codes carefully to avoid any illegal usage.

Detailed Application Rules

Each coupon has four core parameters: service, discount rate, minimal discount, and maximal discount.

When submitting an order, the system calculates the total price of all articles belonging to the specified service as the base.

Then the discount rate of base will be reduced. For example when a coupon with 10% rate of an order of $10 is applied, the discount will be 10% x $10 = $1, the final amount will be (1 - 10%) x $10 = $9 as shown in the table below. Below is another example *.

Article    Num    Price     Total Price
Apple      2      $2        $4
Jeans      1      $10       $10
Coupon [service: 'food', discount rate: 10%, minimal discount: $0, maximal discount: $100]

Final                       $ 14
Discount                    $ -0.4
Final after Discount        $ 13.6

If the discount is less than minimal discount, the coupon is still applied but the discount is set to $0. In the above example, if the minimal discount is set to $2, then the final amount will be $10. Below is another example *.

Article    Num    Price     Total Price
Apple      2      $2        $4
Jeans      1      $10       $10
Coupon [service: 'food', discount rate: 10%, minimal discount: $1, maximal discount: $100]

Final                       $ 14
Discount                    $  0
Final after Discount        $ 14

If the discount is more than maximal discount, the coupon is still applied but the discount is limit so that the discount is not larger than the specified value. In the above example if the maximal discount is set to $0.5 and minimal discount is unset (or set to $0), then the discount will be 5% x $10 = $0.5 and the final amount will be (1 - 5%) x $10 = $9.5, or calculate in this way $10 - $0.5 = $9.5 since the original discount $1 is larger than $0.5. Below is another example *.

Article    Num    Price     Total Price
Apple      2      $2        $4
Jeans      1      $10       $10
Coupon [service: 'food', discount rate: 10%, minimal discount: $0, maximal discount: $0.2]

Final                       $ 14
Discount                    $ -0.2
Final after Discount        $ 13.8

When multiple discounts are applied, the discount is calculated separately from the base.

Article    Num    Price     Total Price
Apple      2      $2        $4
Jeans      1      $10       $10
Coupon1 [service: 'food', discount rate: 10%, minimal discount: $0, maximal discount: $0.2]
Coupon2 [service: 'food', discount rate: 20%, minimal discount: $0, maximal discount: $100]

Final                       $ 14
Discount from Coupon 1      $ -0.2
Discount from Coupon 2      $ -0.8
Final after Discount        $ 13

It's notable that all the discounts are calculated after the tax if specified. Please also be aware that there are ceilings in the calculation, the final discount could be slightly higher than the specification. It's most important when you sell an article with very low price near the minimal unit (e.g. $0.01), please read the next sections for details.

* The examples are helping you to understand the discount. In the actual invoice, the discount won't be listed as a single amount but distributed to the articles.

Distribution of Discount and Handling of Returns

The above examples are helping you to understand the discount. In the actual usage, the total discount is distributed to each article. An example is shown below. Due to the distribution, the actual discount could be slightly higher than the planned discount. In general the difference is very small, but the difference could be large if the price is too low. Considering this example.

The distribution makes return of the articles easier. The real amount after the distributed discount should be sent back [is returned]. It's notable that there's no control of the condition of the discount after the article is returned. This should be fine and fair for the most cases, if you prefer to recheck the condition, it has to be done manually.

Voucher

A voucher is an one-time random code, which is often used as gift card in digital or printed form. A user can apply the code by entering it in their user center to get the specified amount of money assigned to their balance. The balance can be used later to pay the order fully or partially.

Each code has it's own start time and end time (expiration time). A user can only apply a code in this time interval.

To create a voucher, you have to create a voucher group at first, which contains codes with same settings (name, amount, etc.). Then you can add codes to the group. There's an export function allowing you to export multiple codes to CSV table.

Mercury is ready to sell digital products. You can sell the generated voucher code as digital gift cards.

Please protect the codes carefully to avoid any illegal usage .

Backup

Link Your Domain 

You replace your main address by link your domain to our system. In order to do this, you should contact your domain administrator to create a CNAME record or an A record to the built-in main address or it's IP. It's notable that the main address must be a domain name (e.g. yourshop.com), you can't serve your shop under a directory (e.g. yourshop.com/shop). After that, you can go to Information & System / Domain of your management panel and and add a new domain.

Setup Emails 

Mercury no more supports built-in mail sender since these emails will be blocked by many mail servers. You have to prepare a regular SMTP account. Without that all the related function won't work.

Advanced Features

Prometheus Entry Point

We provide a Prometheus (https://prometheus.io/) entry point to monitor the status of your shop. It's available at: https://<your-server-address>/feature/mercury.mercury.mercury/metrics. Please note that it works via https on port 443 instead of regular http protocol on port 9090. A typical Prometheus configuration should look like this:

...

  - job_name: mercury
    scheme: "https"
    metrics_path: "/feature/mercury.mercury.mercury/metrics"
    static_configs:
      - targets: ["your-server-address"]

...

Get Support

Official Website

You can access our official website at https://www.esoul.online. Here you can create support tickets and chat with our team whenever you need help, just like how your customers contact you.

You can also find introduction of other services we offer. You can try everything for free and maybe they can help you to make your business easier.

Help & Training Wiki

We provide a wiki at https://wiki.esoul.online. Here you can find the news, announcements, official help documents and training materials for all our services.

Community Forum

We also provide a community forum at https://forum.esoul.online. Here you can report issues to us, or ask whatever you want to our team and to other users. Meanwhile, we appreciate if you're able to share your experiments to other users searching for help.

Email

You can also reach us via email: info[at]esoul.online. Although it's not the recommended way and it may take longer than other channel to get feedback.

By default, you'll receive impotent announcements periodically from us per email. You may unsubscribe / re-subscribe the news letter whenever you want.

Important Definitions

Name	Description
Subscription	A subscription is a description of a long-term service. It will generate orders periodically, so that the customer don't have to pay the whole amount at the very beginning.
Digital Article	A digital article is a special type of article. The customer will receive a piece of digital code after the article is successfully ordered. The code can be for example a coupon or a digital gift card. The digital article can also be used to sell an 3rd-party services. In this case, the code will be the 3rd-party account credential. Mercury supports backwards validation to validate the credential based on the service time period of the related order.