Shop Configuration

A crucial part of every Shop is the configuration. It allows you to change settings like language, currency, image sizes, authentication, payment gateways. You can also customize the checkout validation logic, order numbering, reviews.

The config is also to be used to enable or disable features like multi-channel, reviews, advanced pricing or tax calculation.

It consists of one or more files in the repository'sconfig/ folder.

The list of possible config files in the config directory:

vanilo.json: configures the ecommerce features
shop.json: basic application configuration
mail.json: e-mail sending configuration
bff.yml: Storefront API documentation customization

Currency

To configure the base currency of your shop, you need to define the following options in the config/vanilo.json file:

{
    "foundation": {
        "currency": {
            "code": "EUR",
            "format": "%1$g %2$s",
            "sign": "€"
        }
    }
}

where the code field's value must be the 3 letter ISO-4217 currency code of the base currency the shop is using.

The sign field will be used to display the prices in the given currency, for example $ (dollar), € (euro), ¥ (yen) or Fr (franc).

The format is an sprintf compatible format string that takes the amount as the first and the currency sign as the second parameter.

The format_price() helper function will use it.

// format: "%1$g %2$s", sign: '€' 
format_price(140)
// => "140 €"

// format: "%2$s%1$g", sign: '$' 
format_price(140)
// => "$140"

Image Sizes

Images uploaded in Admin or via REST API are be resized to various sizes. These are called "variants" and you can freely define the names, sizes and the cropping method of these variants as per your needs.

See the Images Page for detailed information about image handling in Vanilo Cloud

The image sizes need to be defined in the config/vanilo.json file:

{
    "foundation": {
        "image": {
            "variants": {
                "thumbnail": {
                    "width": 250,
                    "height": 250,
                    "fit": "crop"
                },
                "medium": {
                    "width": 500,
                    "height": 360,
                    "fit": "crop"
                }
            }
        }
    }
}

These settings will apply to images of products, taxonomies and taxons.

If you need different variants for any of products/taxonomies/taxons, you can define specific variant for them, that will override the image sizes defined under the foundation.image.variants configuration.

The image configuration can be placed under the following JSON keys:

foundation.image.variants: applies to the images of all entities (product, taxon, taxonomy).
foundation.image.product.variants: applies to product images only, overrides the common image configuration
foundation.image.taxon.variants: applies to taxon images only, overrides the common image configuration
foundation.image.taxonomy.variants: applies to taxonomy images only, overrides the common image configuration

The example below will create a single variant called "banner" for images uploaded to taxons and taxonomies, and two variants called "index" and "preview" for images uploaded to products:

{
    "foundation": {
        "image": {
            "variants": {
                "banner": {
                    "width": 1280,
                    "height": 360,
                    "fit": "crop"
                }
            },
            "product": {
                "index": {
                    "width": 360,
                    "height": 360,
                    "fit": "crop"
                },
                "preview": {
                    "width": 720,
                    "height": 720,
                    "fit": "crop"
                }
            }
        }
    }
}

Fit Methods

The "fit" keys can take the following values:

Method	What it does
`contain`	Resizes the image to fit within the width and height boundaries without cropping, distorting or altering the aspect ratio.
`crop`	Resizes the image to fill the width and height boundaries and crops any excess image data. The resulting image will match the width and height constraints without distorting the image.
`fill`	Resizes the image to fit within the width and height boundaries without cropping or distorting the image, and the remaining space is filled with the background color. The resulting image will match the constraining dimensions.
`stretch`	Stretches the image to fit the constraining dimensions exactly. The resulting image will fill the dimensions, and will not maintain the aspect ratio of the input image.
`max`	Resizes the image to fit within the width and height boundaries without cropping, distorting or altering the aspect ratio, and will also not increase the size of the image if it is smaller than the output size.

Order

The order configuration allows you to define how the order numbers are generated.

Vanilo Cloud has 3 number generators: sequential_number, nano_id and time_hash (default).

To set the order number generator, set the order.number.generator key in the vanilo.json file:

{
    "order": {
        "number": {
            "generator": "nano_id"
        }
    }
}

Each generator has further settings, that are described below.

Sequential Number

Generates a sequential order number like 5684975 or ORD-0078. Further settings allow you to set the starting number, a prefix, and padding:

{
    "order": {
        "number": {
            "generator": "sequential_number",
            "sequential_number": {
                "start_sequence_from": 100,
                "prefix": "ORD-",
                "pad_length": 4,
                "pad_string": 0
            }
        }
    }
}

The example above will generate order numbers: ORD-0100, ORD-0101, ORD-0102 and so on.

Time Hash

This is the default order number generator

Uses the current date and time down to milliseconds and some randomness to generate a unique sequence of letters like "6P3-0EB3-79G8".

{
    "order": {
        "number": {
            "generator": "time_hash",
            "time_hash": {
                "start_base_date": "2024-01-01",
                "uppercase": true,
                "high_variance": false
            }
        }
    }
}

The start_base_date setting influences where the number generation starts from.

If the high_variance is enabled then the generated number will be longer like "6TF-0QFC-30U2-71FN". This setting should be enabled if you expect processing at least 20 order per second.

Nano ID

Generates a Nano ID like "7YV9PC7QEZE6" for the order number.

By default, the nano id generator creates a 12 character long id, using only digits 0-9 and uppercase characters A-Z. You can change the size and the characters used in the ID. It's not recommended to use shorter than 8-10 character long order numbers to avoid possible duplicates.

{
    "order": {
        "number": {
            "generator": "nano_id",
            "nano_id": {
                "size": "10",
                "alphabet": "123456789ABCDEFGHIJKLMNPQRSTUVWXYZ"
            }
        }
    }
}

The example above will generate 10 character long nano ids, and won't use 0 and O characters in the generated numbers.

Checkout

shipping_countries
billing_countries
validation rules

Payment

Redirect URLs

Tax Configuration

vanilo.json

{
    "taxes": {
        "engine": {
            "driver": "none(default)|simple|eu|canada"
        }
    }
}

Features

To enable extra, non-default features in your shop, set the features.<feature_name>.is_enabled config value to true:

{
    "features": {
        "multi_channel": {
            "is_enabled": true
        },
        "pricing": {
            "is_enabled": true
        }
    }
}

These are the Vanilo Cloud features which are turned off by default:

For further usage and configuration details refer to each feature's documentation page.