Frequently Asked Questions
We're collecting the questions we get most often into a list of FAQs. If your question is not in the list, please reach out to us via [email protected] and we would be glad to help.
When will Commerce be available?
It already is!
Commerce is formally in public beta. While we consider it stable, and ready to use in production like many of our customers are indeed doing, Commerce is missing a few features that we consider important to implement in version 1.0, which you can read more about in our roadmap.
After years of hard work, we expect to release Commerce 1.0 later this year, and will definitely be hosting a party when that happens.
How much does Commerce cost?
Commerce is priced at €299 per license. A license is valid for one MODX installation, and includes all future 1.x upgrades and our standard email support.
Free development licenses are available for development and for trying out Commerce prior to purchasing a license.
We offer discounts for non-profit organisations that meet our requirements.
How does Commerce handle product prices and sales tax/VAT?
Taxes in Commerce are quite flexible. They are organised around Tax Groups, assigned to your products, and Tax Rules that determine when a certain Rate Provider should be used.
Product prices can be configured to be either inclusive or exclusive of taxes. When a customer address is available, taxes will be shown as soon as a product is added to the cart.
What are the requirements for running Commerce?
For Commerce we've set slightly higher requirements than our other extras.
- PHP 5.5+ (5.6 or higher strongly recommended)
- MODX Revolution 2.5.2 or higher
- Valid HTTPS certificate and configuration on the website
It is possible to install Commerce without meeting all of these requirements right away, however you will be warned about the lacking configuration on the dashboard, and may not be able of switching the shop to live mode depending on what requirement is missing.
What will happen to SimpleCart when Commerce is released?
We'll continue providing support for it and improving it for at least a year after the first Commerce 1.0 stable release. Over the next couple of months we'll work on at least one more Payment Gateway for SimpleCart and adding some improvements to make it more flexible. We wrote about this in more detail: How Commerce affects SimpleCart.
One of the cool things about Commerce is that it allows you to use different tools to manage your catalog of products. The SimpleCart custom resources are a great example of what you might use for managing your catalog, so rather than throwing SimpleCart out with the bath water, we intend to offer a solid integration between the two.
How can I manage products in Commerce?
Commerce introduces a divide between the customer-facing Catalog and the internal Products that it requires to calculate totals and handle orders.
The Catalog is your front-end. It's how customers browse through what your webshop has to offer, including product information, different variations, photos or videos, reviews, and so on. How you build this catalog is completely up to you: it can consist of resources, Collections, MIGX TVs, SimpleCart product resources, a POS or ERP system, custom tables or third party database... the possibilities are limited to your imagination (and skills and/or budget).
Products are simple database objects consisting of a product's name, description, SKU, stock level, and price. These products are what Commerce does care about. When a customer sees an item they'd like to purchase in your catalog, they will add this Product to their cart.
It's possible to manage products within resources, separately, or integrated with something custom.
How can I change the markup (HTML) templates used in the cart or checkout?
Commerce uses Twig file-based templates for its theming. The documentation has more in-depth information on how to use that, but here's the basics.
- Create a new folder under
core/components/commerce/templates/with a name of your choosing*. For example
design2017. The name of this folder is your theme name.
- Edit the
commerce.themesystem setting and set it to the name of your theme.
- Locate the template file you wish to edit (for example
default/frontend/checkout/cart.twig) and copy it into your own theme folder with the same name and directory structure (for example
- Edit your copy.
It's not recommended to copy over all template files, just the ones you have edited.
* It's also possible to place the template folder somewhere else using the
commerce.theme_path setting. See the documentation for more detailed information about the possibilities for themes.
Does Commerce offer different shop designs or themes?
No. Commerce has only one "theme" for the cart and checkout that adds a basic design to the default markup. This theme consists of two CSS files that are registered to the site header, layout.css and style.css.
The layout.css file contains some basic layout-related css definitions to position things fairly intuitively. It contains no colors, fonts, borders or other style decisions.
The style.css enhances the layout.css styles to make it look pretty. This is more opinionated and may or may not look great with the rest of your design. It still inherits as much as possible from your existing CSS (for example font-sizes use em to be relative to the size on your body) but does define colors and backgrounds.
commerce.register_checkout_css system setting determines if these two files are loaded. Set it to 1 to load the files automatically on your cart and checkout pages, or set it to 0 to not load them.
How can I automate (part of) the merchant order fulfilment?
Most order-specific automation will happen through the status workflow that you define.
Basically whenever you manage an order and want to change its status, you will need to choose a Status Change instead of the new status. The status change controls the flow the order goes through from the customer going through checkout, all the way through the products getting shipped.
For each Status Change, you can add Status Change Actions that happen when the status is changed. These status change actions include sending emails to the customer or merchant, but with a bit of development you can also create status change actions that automatically print shipment labels, sends order and customer information to a CRM or ERP system, or does something else entirely.
Through these actions you can automate a whole lot of normally labour intensive tasks to ensure your fulfilment works at top efficiency .
Does Commerce support multi-context setups?
Sure, your shop can be spread across different contexts. They'd all be served from the same MODX installation (on a single hostname) and a single Commerce dashboard. The product records would be shared across the MODX installations, but your catalog could be vastly different per context.
It's possible to use different templates per context, as well as different cart/checkout pages with context-specific settings.
It's also possible to set a different currency per context, which requires you to have context-specific cart and checkout pages as well, however multi-currency support is fairly limited at this point.
Can Commerce integrate with my CRM, ERP or POS system?
When we built Commerce, we made sure it was easy to extend and integrate, so yes you will be able of integrating it with any three-letter-acryonym system.
If you'd like to commission an integration, please contact Mark via [email protected] with details to receive an estimate and information about the possibilities and availability.
Will Commerce file my taxes for me?
It wont file them for you, but it does have reports and exports that will help you with that. Please see the features list or documentation for the available reports and be sure to file a feature request if you have specific needs that are not yet met. It's also possible to create your own reports that can be used to output the information exactly like you need it.
How do I enable/disable the standard cart/checkout theme CSS?
Can I put my template (theme) files in a different directory?
By default Commerce looks inside
core/components/commerce/templates/ for your theme files. If you'd like to have it also look in a different theme directory, such as
/assets/checkout/, you can specify the
commerce.theme_path system setting with the absolute path to your template directory.
When setting a theme path, you still need to create a folder inside that directory that matches your theme name as configured in
What payment providers does Commerce support?
As of October 2018, the following payment providers are available:
- Adyen (Hosted payment page, various payment options, separately installed)
- Manual (dummy gateway that just marks the order as paid for testing)
- Mollie (Dutch gateway offering iDeal, Sofort, Bancontact, PayPal, CreditCard and more)
- MultiSafePay (Wide range of payment methods, including iDeal and CreditCard)
- PayPal Express (off-site hosted checkout with PayPal accounts or guest checkout with credit card)
- SagePay (off-site hosted credit card payments)
Read more about each of the payment gateways in the documentation. The Roadmap has a list of other gateways we're planning or considering. Be sure to send us a feature request for the gateway you need if it's not listed or planned yet!
Does Commerce support one-page checkout?
A true one-page checkout is not really possible, as Commerce requires information from the previous step to show the next. For example it's not possible to determine available shipping methods until the customer provided their address, and it's not possible to show payment methods before the order total is confirmed based on the chosen shipping method.
As the templating uses Twig, can I still use MODX snippets or tags?
Why does Commerce use Twig instead of standard MODX tags?
Twig brings a more powerful templating language to Commerce. Simple conditionals, loops and includes are all possible in Twig, which would become a rather complicated set of snippets and chunks with the standard MODX parser.
As templates are stored in files, they're also much easier to include in version control compared to chunks.
The Twig for Template Designers documentation is a good starting point if you haven't worked with Twig before.
Do you offer non-profit discounts for Commerce?
Yes, to select organisations that meet our requirements we will offer up to 50% off on a Commerce license. For the process and requirements, see the Commerce Pricing.
Should I migrate my SimpleCart store to Commerce?
If you're happy with SimpleCart, you can continue to use it. We'll still support it, so you don't have to migrate just because we've got something shiny and new.
If you're doing a redesign or rebuild of a previously SimpleCart-powered shop, we would recommend looking into the differences (see the documentation for a summary) and determining whether SimpleCart, Commerce, or both are the best match for your store.
Does Commerce support multiple currencies?
Yes, but it's only basic support for now. You can set a different currency per context, which will affect the price formatting the customer sees. Orders placed within different contexts will also keep track of the used currency, so in your merchant dashboard you can see what currency the customer used for their order and payment.
However, Commerce does not currently support currency-specific product prices, so you will need to create different products in different currencies, or a custom product type that does keep track of different currencies.
Not all of the reports are currency aware, meaning they might clump together amounts in somewhat unpredictable ways.
Can I restrict my shop to specific countries?
Yes, using the Country Validation module provided with Commerce you can set up a blacklist or whitelist of countries that are allowed to place an order. This will warn customers that their country is not currently supported when they try to place their order. See the documentation for more information on this module.
How is address validation handled in Commerce?
There is a basic address validation module available in Commerce which will make sure the required fields are filled in, and that the email is syntactically valid. It also checks if a valid country was selected. See the documentation here.
The module does not verify if an address is accurate, but it's possible for developers to build a validation module that verifies an address is real.
Is it possible for my (logged in) customers to use their previously used address during checkout?
Yes, this is built-in to Commerce. When logged in users visit the checkout after placing an order previously, it will show their previously used shipping and/or billing address to reuse.
Additionally, the core-provided User Profile Address module will prefill the "new address" form with the information from the user profile. That can also update the address on their profile. This module is mostly useful if other parts of your site rely on the address on the profile being accurate/filled.
When adding a product that is already in the cart, it is duplicated. Can this be combined?
Yes, enable the Combine Products module to automatically combine products that get added to the cart multiple times into a single item.
How does Commerce handle multilingual shops?
With the separation of products and your catalog, there are many different ways you can build a multilingual shop.
With MODX, there are roughly 2 ways to handle multilingual sites in general. First is the multi-context approach, where different languages have their own context and resources. Secondly there is an integrated approach where a single context is used to serve different languages, for example with MIGX or Lingua to manage translations.
The Commerce cart and checkout use lexicons by default, so your cart and checkout will automatically use the right language if you set the cultureKey appropriately on different contexts. With integrated translations, you'll need to make sure the right cultureKey is set dynamically.
Products are not currently translatable.
Is it possible to skip or force the account step in the checkout?
Yes, different ways of dealing with user accounts in the checkout are supported. You can make it required to be logged in, you can make it optional (default), or you can hide the account step completely. See the documentation for how this can be configured.
Is it possible to skip or force the Shipping Method selection step in the checkout?
Yes, this is managed on your Delivery Type. You can set the shipping step to either be always shown, never shown, or that it depends on how many options are available for the customer to choose with their order.
The checkout automatically selects the first shipping method that is available, no matter what you set it to.
Because the shipping step is configured by delivery type, you can set different strategies for different types of products. You may for example hide the shipping step for digital products (vouchers, ebooks), while setting it to "depends" for physical products.
Where can I change what emails are sent when an order is placed?
With the default status workflow that is created during the installation of Commerce, you'll find them in the "Payment Received" status change. Navigate to Extras > Commerce > Configuration > Statuses, and click on "Payment Received" in the middle column. It should have the bold text "Used on payment received" below the name.
In the Status Change Actions grid for the status workflow, you'll see two emails:
- Confirmation Email to Customer. This email is configured to go to the customer and uses the template
- Order Notification for Merchant. This email is configured to go to the email address that was set in the emailsender system setting when Commerce was installed, and uses the
You can add email status actions to any part of your status workflow. There is for example an
emails/shipping-confirmation.twig template included in Commerce that can be used as part of an "Order Shipped" status change.
How do I customise the emails that are sent for a new order?
To manage the configuration of the email (the email addresses to use and template), you can go to Extras > Commerce > Configuration > Statuses. Click on the name of the status change that runs when payment is received, usually that's a status change aptly called "Payment Received", and you'll find the list of outgoing emails there. You can change the subject, email addresses, and content by editing the email status change actions.
Add header image and footer text
You can easily add a header image to all outgoing emails by setting the
commerce.email_header_url to a fully qualified URL of the image to use for the header or logo. This should be a full URL, including your site url. The default template (
emails/wrapper.twig) assumes the image to be 500x120px.
The text in the
commerce.email_footer_text system setting will be added to the footer of all outgoing emails and would typically need to include information about your registered address or terms and conditions. This setting can include HTML. If not set it will show the site name instead.
If you're happy with the basic configuration, you can change the text used in lexicons. By default Commerce is translated into many languages, so you should hopefully find the emails are already translated, but if you want to change the text you can do so from the MODX manager.
- Go to System > Lexicons in MODX.
- Choose "commerce" for the namespace and leave the topic set to "default". Choose the language if you want to change it for a language other than English.
- Enter "email" in the search field on the right of the toolbar. This will give you most (if not all) email-related lexicons used by Commerce. Look at the name; if it includes order_rcvd it is part of the email to the customer, and order_rcvdmerch is for the email notification to the merchant.
- Once you've found the text you want to change, double click its value to edit it.
Changes made to lexicons in this way are persisted across updates.
The templates for emails are
emails/order-received.twig (for the customer) and
emails/order-to-merchant.twig (for the merchant). Learn more about templating in Commerce here.
How can I make a phone number, or other address fields, required/optional?
By default, all address fields are optional.
Commerce ships with a Basic Address Validation module that allows you to mark which fields are required. It's strongly encouraged to enable this module on all shops, unless you have another module in place that validates the address exists.
To change the required fields with the Basic Address Validation module, navigate to Extras > Commerce > Modules and find Basic Address Validation in the list. Click its name, make sure the module is enabled, and enter a comma-separated list of fields in the "Required Fields" option. The full list of possible fields is available in the documentation. The module makes sure the fields have a value, and for email and country fields it does some additional checking to make sure it's a valid value.