Dot All Lisbon – the official Craft CMS conference – is happening September 23 - 25.

Config Settings

In addition to the settings in CommerceSettings, 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' returns 0 if the result from 'default' would’ve been negative; minimum order total is 0.
  • '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'