====================
Instance management
====================

Instances allow one merchant backend to be shared by multiple merchants (multiple shops). Every backend must have at least one instance,
typically the **"default"** instance setup before it can be used to manage inventory or process payments.

The "default" instance is the **main admin** and is required to manage other instances.

Instance overview
=================

To view all instances, navigate to the **"List"** page in the sidebar section **"Instances"**.
This page displays a complete list of instances along with essential details like instance **ID** and business **name**.

There are subpages under **Instances**:

- **Active**: Displays all currently running instances.
- **Deleted**: Displays instances that have been removed but not yet permanently purged.

To view all orders for a specific instance, click on its **Instance ID**.

Adding a new instance
=====================

Before creating additional instances, ensure you are logged in to the **default** instance.

To add a new instance:

- Click the **"+ New"** button in the **"Instances"** section of the sidebar.
- Alternatively, go to the **"List"** page and click the **"+"** button in the top-right corner.

Simple instance creation
------------------------

This method allows quick setup with minimal details:

- **Identifier** (*required, URL friendly*): If creating the default instance, it will be inactive and set as default.
- **Business name** (*required*): Legal name of the business represented by this instance.
- **Enable access control**: If enabled, you must set a password to access the website or make API calls.

  | We strongly recommend enabling this option and setting a password unless you are using the Merchant Backend for testing
  | or have set up a `reverse proxy <https://docs.taler.net/taler-merchant-manual.html#service-address>`_ through Nginx or Apache.

- **New access token**: Password for access control.
- **Repeat access token**: Repeat password for access control.

Once completed, click the **"Confirm"** button to create an instance.

Advanced instance creation
--------------------------

For additional business details on receipts and compliance requirements, use this option. You can always edit these details later.
All fields from **"Simple instance creation"** section are included, plus:

Contact information
~~~~~~~~~~~~~~~~~~~
.. TODO: Check email purpose

- **Email**: Business contact email.
- **Website URL**: Official website of the business.
- **Logo**: Upload a business logo.

Business address & Jurisdiction address
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This information will be put into contracts.

Expand these sections to enter detailed location information:

- Country
- Address
- Building number
- Building name
- Street
- Post code
- Town location
- Town
- District
- Country subdivision

Payment settings
~~~~~~~~~~~~~~~~

- **Pay transaction fee**: Defines who covers deposit fees (Merchant/Customer).
- **Default payment delay**: Default time for customers to complete payments (default: 2 hours).
- **Default wire transfer delay**: Maximum time for the exchange to transfer funds to the merchant's bank account.

Once all fields are filled, click **"Confirm"** to create the instance.

.. note::
   For more on payment & wire transfer delays, refer to `this tutorial <coming%20soon!>`_.

Editing an instance
===================

To edit another instance, you need to log in to the **default** instance.

To edit the current instance, navigate to the **"Settings"** page in the sidebar.
All fields from the **"Advanced instance creation"** section can be modified here.

Deleting an instance
====================

To delete an instance:

1. Log in to the **"default"** instance.
2. Navigate to **"List"** in the **"Instances"** section.
3. Click **"Delete"** next to the instance.

.. warning::
   Deleted instances are not permanently removed. They remain in the **Deleted** section until purged.

.. note::
   After deleting an instance, the ability to create orders is disabled. This feature is designed to preserve order history for compliance reasons (e.g., taxes, audits, etc.).


Permanently removing an instance
--------------------------------

To completely remove an instance:

- Go to the **"Deleted"** section.
- Click **"Purge"** to erase the instance permanently, including all associated data.

.. warning::
   This action is irreversible.