========================
Billing / Config Options
========================

Configurable options are used to define additional choices on ordering services. For example, a dedicated IP address or
additional storage space for a cPanel shared hosting account.

The **Config. options** page lists all configurable options available, that can be associated with products.

.. image:: /_static/images/staff/billing/config_options/config_options_list.png

After a configurable option is :doc:`associated with a product </staff/billing-products>`, end-users can see the
configurable option during the order process.

.. note::

    A configurable option is not shown on order if it does not have all the associated product's cycles defined.

The configurable option price is defined globally and cannot be overwritten per service. However, you can overwrite the
total price of a service.

If you change the configurable option pricing, it will automatically reflect on all services having the configurable
option associated. The change applies when a new cycle is (automatically) created for a pre-paid service. Pre-paid
service cycles that are already created and already issued invoices are not changed when a related
configurable option price is changed.

Post-paid service (e.g. OpenStack) price is updated on each "process clients" task run, applying any configurable option
price change to in-progress billing cycles.

------------
Option types
------------

The following option types are available:

* Dropdown
    * shows a predefined list of options with or without an associated price
    * only one option can be selected
* Radio
    * shows all options as an HTML radio group
    * only one option can be selected
* Yes/No
    * shows a checkbox that when checked means *yes* and not checked means *no*
* Quantity input
    * shows an input of type number, allowing the client to specify a number
    * price is calculated, if defined, based on the number entered
* Text input
    * shows an input of type text
    * does not have any price associated

The **Status** field defines the configurable option availability as follows: 
 * **public** will make the option visible for the associate products if all the other conditions are met (see below)
 * **private** will only allow staff members to associate an option with a product prior to setup
 * **retired** helps by keeping old selected options associated without the ability to use them for new services

An option can also be marked as **Required** forcing a client to specify a value for that option when asked.
For *Quantity input* types, there are also additional validation fields that allow setting of a minimum, maximum and
step size for the quantity.


.. image:: /_static/images/staff/billing/config_options/config_option_details.png

---------------------
Option billing cycles
---------------------

Configurable option's billing cycle defines billing intervals.

Billing cycle fields:

* **Cycle**: select one of *One Time*, *Day*, *Month*, *Year*
* **Cycle multiplier**: enter a number. For example selecting Month and entering 3 as multiplier means every 3 months.
* **Currency**: select the currency the prices will be expressed in. Do note that options only appear for products that
* **Auto calculate prices**: only available when a non-default currency is selected. If price for the default currency
  is already defined, the price is calculated automatically based on the exchange rate.
* Use **Fixed price** to fill in an actual monetary value. Use **Percentage of product price** to define configurable
  option cycle price as percentage of the product price. If **Apply percentage to other configurable options price** is
  checked, the percentage applies to the product price plus product's other configurable options price. 
* **Setup fee**: applied only once, on order. Leave zero for no cost.

--------------
Option choices
--------------

For *Dropdown* and *Radio*, choices will need to be defined and each choice will need to have billing cycles defined.
Each choice has a **Label** and a **Value**. The label has display purposes only and will appear on invoices and
shopping cart while the value is used for billing and setup.
Once a choice is added, billing cycles can be created and prices defined for that choice.

.. image:: /_static/images/staff/billing/config_options/billing_cycle_choices.png

--------------------------------
Option association with products
--------------------------------

To associate a configurable option with a product, go to the product details at the
**CONFIGURABLE OPTIONS** tab:

.. image:: /_static/images/staff/billing/config_options/associate_config_option.png

Select one of the available options and click the associate button.
Please note the **Product cycles match** column that indicates whether all the product billing cycles are also available
for the configurable option. Not having all the billing cycles matched may not allow this option to be selected all the
time by a client when ordering the product.

.. image:: /_static/images/staff/billing/config_options/config_option_associated.png

Once completed, this option can be selected when ordering a new product

.. image:: /_static/images/staff/billing/config_options/cart_option.png