Dot All Lisbon – the official Craft CMS conference – is happening September 23 - 25.
Config Settings
In addition to the settings in Commerce → Settings, the config items below can be saved in a config/commerce.php
file using the same format as Craft’s general config settings.
For example, if you wanted to change the inactive carts duration in dev environments but not on staging or production, you could do this:
return [
// Global settings
'*' => [
// ...
],
// Dev environment settings
'dev' => [
'purgeInactiveCartsDuration' => 'P1D',
// ...
],
// Staging environment settings
'staging' => [
// ...
],
// Production environment settings
'production' => [
// ...
],
];
You can access the Commerce general settings model in your templates:
{% set settings = craft.commerce.settings %}
Here’s the full list of Commerce config settings:
System
defaultView
- Allowed types
- string
- Default value
'commerce/orders'
- Defined by
- Settings::$defaultView
- Since
- 2.2
Commerce’s default control panel view. (Defaults to order index.)
emailSenderAddress
- Allowed types
- string, null
- Default value
null
- Defined by
- Settings::$emailSenderAddress
Default email address Commerce system messages should be sent from.
If null
(default), Craft’s MailSettings::$fromEmail will be used.
emailSenderAddressPlaceholder
- Allowed types
- string, null
- Default value
null
- Defined by
- Settings::$emailSenderAddressPlaceholder
Placeholder value displayed for the sender address control panel settings field.
If null
(default), Craft’s MailSettings::$fromEmail will be used.
emailSenderName
- Allowed types
- string, null
- Default value
null
- Defined by
- Settings::$emailSenderName
Default from name used for Commerce system emails.
If null
(default), Craft’s MailSettings::$fromName will be used.
emailSenderNamePlaceholder
- Allowed types
- string, null
- Default value
null
- Defined by
- Settings::$emailSenderNamePlaceholder
Placeholder value displayed for the sender name control panel settings field.
If null
(default), Craft’s MailSettings::$fromName will be used.
showEditUserCommerceTab
- Allowed types
- boolean
- Default value
true
- Defined by
- Settings::$showEditUserCommerceTab
- Since
- 4.0
Whether the Commerce Tab should be shown when viewing users in the control panel.
Cart
activeCartDuration
- Allowed types
mixed
- Default value
3600
(1 hour)- Defined by
- Settings::$activeCartDuration
- Since
- 2.2
How long a cart should go without being updated before it’s considered inactive.
See craft\helpers\ConfigHelper::durationInSeconds() for a list of supported value types.
allowCheckoutWithoutPayment
- Allowed types
- boolean
- Default value
false
- Defined by
- Settings::$allowCheckoutWithoutPayment
- Since
- 3.3
Whether carts are can be marked as completed without a payment.
allowEmptyCartOnCheckout
- Allowed types
- boolean
- Default value
false
- Defined by
- Settings::$allowEmptyCartOnCheckout
- Since
- 2.2
Whether carts are allowed to be empty on checkout.
autoSetCartShippingMethodOption
- Allowed types
- boolean
- Default value
false
- Defined by
- Settings::$autoSetCartShippingMethodOption
Whether the first available shipping method option should be set automatically on carts.
autoSetNewCartAddresses
- Allowed types
- boolean
- Default value
true
- Defined by
- Settings::$autoSetNewCartAddresses
Whether the user’s primary shipping and billing addresses should be set automatically on new carts.
autoSetPaymentSource
- Allowed types
- boolean
- Default value
false
- Defined by
- Settings::$autoSetPaymentSource
- Since
- 4.2
Whether the user’s primary payment source should be set automatically on new carts.
cartVariable
- Allowed types
- string
- Default value
'cart'
- Defined by
- Settings::$cartVariable
Key to be used when returning cart information in a response.
loadCartRedirectUrl
- Allowed types
- string, null
- Default value
null
- Defined by
- Settings::$loadCartRedirectUrl
- Since
- 3.1
Default URL to be loaded after using the load cart controller action.
If null
(default), Craft’s default siteUrl
will be used.
purgeInactiveCarts
- Allowed types
- boolean
- Default value
true
- Defined by
- Settings::$purgeInactiveCarts
Whether inactive carts should automatically be deleted from the database during garbage collection.
::: tip
You can control how long a cart should go without being updated before it gets deleted purgeInactiveCartsDuration
setting.
:::
purgeInactiveCartsDuration
- Allowed types
mixed
- Default value
7776000
(90 days)- Defined by
- Settings::$purgeInactiveCartsDuration
Default length of time before inactive carts are purged. (Defaults to 90 days.)
See craft\helpers\ConfigHelper::durationInSeconds() for a list of supported value types.
updateCartSearchIndexes
- Allowed types
- boolean
- Default value
true
- Defined by
- Settings::$updateCartSearchIndexes
- Since
- 3.1.5
Whether the search index for a cart should be updated when saving the cart via commerce/cart/*
controller actions.
May be set to false
to reduce performance impact on high-traffic sites.
::: warning
Setting this to false
will result in fewer index update queue jobs, but you’ll need to manually re-index orders to ensure up-to-date cart search results in the control panel.
:::
validateCartCustomFieldsOnSubmission
- Allowed types
- boolean
- Default value
false
- Defined by
- Settings::$validateCartCustomFieldsOnSubmission
- Since
- 3.0.12
Whether to validate custom fields when a cart is updated.
Set to true
to allow custom content fields to return validation errors when a cart is updated.
Orders
freeOrderPaymentStrategy
- Allowed types
- string
- Default value
'complete'
- Defined by
- Settings::$freeOrderPaymentStrategy
How Commerce should handle free orders.
The default 'complete'
setting automatically completes zero-balance orders without forwarding them to the payment gateway.
The 'process'
setting forwards zero-balance orders to the payment gateway for processing. This can be useful if the customer’s balance
needs to be updated or otherwise adjusted by the payment gateway.
minimumTotalPriceStrategy
- Allowed types
- string
- Default value
'default'
- Defined by
- Settings::$minimumTotalPriceStrategy
How Commerce should handle minimum total price for an order.
Options:
'default'
rounds the sum of the item subtotal and adjustments.'zero'
returns0
if the result from'default'
would’ve been negative; minimum order total is0
.'shipping'
returns the total shipping cost if the'default'
result would’ve been negative; minimum order total equals shipping amount.
orderReferenceFormat
- Allowed types
- string
- Default value
'{{number[:7]}}'
- Defined by
- Settings::$orderReferenceFormat
Human-friendly reference number format for orders. Result must be unique.
See Order Numbers.
pdfAllowRemoteImages
- Allowed types
- boolean
- Default value
false
- Defined by
- Settings::$pdfAllowRemoteImages
Whether to allow non-local images in generated order PDFs.
pdfPaperOrientation
- Allowed types
- string
- Default value
'portrait'
- Defined by
- Settings::$pdfPaperOrientation
The orientation of the paper to use for generated order PDF files.
Options are 'portrait'
and 'landscape'
.
pdfPaperSize
- Allowed types
- string
- Default value
'letter'
- Defined by
- Settings::$pdfPaperSize
The size of the paper to use for generated order PDFs.
The full list of supported paper sizes can be found in the dompdf library.
requireBillingAddressAtCheckout
- Allowed types
- boolean
- Default value
false
- Defined by
- Settings::$requireBillingAddressAtCheckout
Whether a billing address is required before making payment on an order.
requireShippingAddressAtCheckout
- Allowed types
- boolean
- Default value
false
- Defined by
- Settings::$requireShippingAddressAtCheckout
Whether a shipping address is required before making payment on an order.
requireShippingMethodSelectionAtCheckout
- Allowed types
- boolean
- Default value
false
- Defined by
- Settings::$requireShippingMethodSelectionAtCheckout
Whether shipping method selection is required before making payment on an order.
updateBillingDetailsUrl
- Allowed types
- string
- Default value
''
- Defined by
- Settings::$updateBillingDetailsUrl
URL for a user to resolve billing issues with their subscription.
::: tip The example templates include a template for this page. :::
useBillingAddressForTax
- Allowed types
- boolean
- Default value
false
- Defined by
- Settings::$useBillingAddressForTax
Whether taxes should be calculated based on the billing address instead of the shipping address.
validateBusinessTaxIdAsVatId
- Allowed types
- boolean
- Default value
false
- Defined by
- Settings::$validateBusinessTaxIdAsVatId
Whether to enable validation requiring the businessTaxId
to be a valid VAT ID.
When set to false
, no validation is applied to businessTaxId
.
When set to true
, businessTaxId
must contain a valid VAT ID.
::: tip This setting strictly toggles input validation and has no impact on tax configuration or behavior elsewhere in the system. :::
Payments
allowPartialPaymentOnCheckout
- Allowed types
- boolean
- Default value
false
- Defined by
- Settings::$allowPartialPaymentOnCheckout
Whether partial payment can be made from the front end when the gateway allows them.
The false
default does not allow partial payments on the front end.
gatewayPostRedirectTemplate
- Allowed types
- string
- Default value
''
- Defined by
- Settings::$gatewayPostRedirectTemplate
The path to the template that should be used to perform POST requests to offsite payment gateways.
The template must contain a form that posts to the URL supplied by the actionUrl
variable and outputs all hidden inputs with
the inputs
variable.
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Redirecting...</title>
</head>
<body onload="document.forms[0].submit();">
<form action="{{ actionUrl }}" method="post">
<p>Redirecting to payment page...</p>
<p>
{{ inputs|raw }}
<button type="submit">Continue</button>
</p>
</form>
</body>
</html>
::: tip Since this template is simply used for redirecting, it only appears for a few seconds, so we suggest making it load fast with minimal images and inline styles to reduce HTTP requests. :::
If empty (default), each gateway will decide how to handle after-payment redirects.
paymentCurrency
- Allowed types
- array, null
- Default value
null
- Defined by
- Settings::$paymentCurrency
ISO codes for supported payment currencies.
See Payment Currencies.
Units
dimensionUnits
- Allowed types
- string
- Default value
'mm'
- Defined by
- Settings::$dimensionUnits
Unit type for dimension measurements.
Options:
'mm'
'cm'
'm'
'ft'
'in'
weightUnits
- Allowed types
- string
- Default value
'g'
- Defined by
- Settings::$weightUnits
Units to be used for weight measurements.
Options:
'g'
'kg'
'lb'