Configuring Commerce

Commerce supports a number of settings. Like Craft’s config settings, you can override their default values in a config/commerce.php file.

return [
    'purgeInactiveCartsDuration' => 'P1D',
];

In Commerce 5, many global settings have become store-specific. See the upgrade guide for more information.

# Aliases

Commerce adds these aliases on top of those provided by Craft.

Alias Description
@commerceLib The path to vendor/craftcms/commerce/lib/

# Environmental Configuration

Some Commerce settings can be defined on a per-environment basis using environment variables or aliases:

  • System Settings →
    • General Settings →
      • Subscription Settings →
        • Billing detail update URL
    • Emails →
      • Status Email Address (Environment variables only)
      • From Name (Environment variables only)

# Project Config

Craft Commerce stores the following items in the Craft project config:

  • Commerce general settings
  • Stores
  • Order, product, variant, and subscription field layouts
  • Order statuses
  • Product types
  • Email settings
  • PDF settings
  • Gateways settings

Some items are considered “content” and can change in production, meaning they’re not stored in project config:

  • Pricing rules
  • Discounts and sales
  • Shipping categories
  • Shipping zones
  • Shipping methods and rules
  • Subscription plans
  • Tax categories
  • Tax zones
  • Tax rates
  • Order, product, variant, and subscription elements

# Config Settings

# System

# defaultView

Allowed types
string (opens new window)
Default value
'commerce/orders'
Defined by
Settings::$defaultView (opens new window)
Since
2.2

Commerce’s default control panel view. (Defaults to order index.)

# Cart

# activeCartDuration

Allowed types
mixed
Default value
3600 (1 hour)
Defined by
Settings::$activeCartDuration (opens new window)
Since
2.2

How long a cart should go without being updated before it’s considered inactive.

See craft\helpers\ConfigHelper::durationInSeconds() (opens new window) for a list of supported value types.

# cartVariable

Allowed types
string (opens new window)
Default value
'cart'
Defined by
Settings::$cartVariable (opens new window)

Key to be used when returning cart information in a response.

# loadCartRedirectUrl

Allowed types
string (opens new window), null (opens new window)
Default value
null
Defined by
Settings::$loadCartRedirectUrl (opens new window)
Since
3.1

Default URL to be loaded after using the load cart controller action (opens new window).

If null (default), Craft’s default siteUrl will be used.

# purgeInactiveCarts

Allowed types
boolean (opens new window)
Default value
true
Defined by
Settings::$purgeInactiveCarts (opens new window)

Whether inactive carts should automatically be deleted from the database during garbage collection.

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 (opens new window)

Default length of time before inactive carts are purged. (Defaults to 90 days.)

See craft\helpers\ConfigHelper::durationInSeconds() (opens new window) for a list of supported value types.

# updateCartSearchIndexes

Allowed types
boolean (opens new window)
Default value
true
Defined by
Settings::$updateCartSearchIndexes (opens new window)
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.

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 (opens new window)
Default value
false
Defined by
Settings::$validateCartCustomFieldsOnSubmission (opens new window)
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

# pdfAllowRemoteImages

Allowed types
boolean (opens new window)
Default value
false
Defined by
Settings::$pdfAllowRemoteImages (opens new window)

Whether to allow non-local images in generated order PDFs.

# updateBillingDetailsUrl

Allowed types
string (opens new window)
Default value
''
Defined by
Settings::$updateBillingDetailsUrl (opens new window)

URL for a user to resolve billing issues with their subscription.

The example templates include a template for this page (opens new window).

# Payments

# gatewayPostRedirectTemplate

Allowed types
string (opens new window)
Default value
''
Defined by
Settings::$gatewayPostRedirectTemplate (opens new window)

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>

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 (opens new window), null (opens new window)
Default value
null
Defined by
Settings::$paymentCurrency (opens new window)

ISO codes for supported payment currencies.

See Payment Currencies (opens new window).

# Units

# dimensionUnits

Allowed types
string (opens new window)
Default value
'mm'
Defined by
Settings::$dimensionUnits (opens new window)

Unit type for dimension measurements.

Options:

  • 'mm'
  • 'cm'
  • 'm'
  • 'ft'
  • 'in'

# weightUnits

Allowed types
string (opens new window)
Default value
'g'
Defined by
Settings::$weightUnits (opens new window)

Units to be used for weight measurements.

Options:

  • 'g'
  • 'kg'
  • 'lb'

# Advanced Configuration

Additional customization of Commerce components is possible via application configuration. These settings must be added to your project’s config/app.php file, within the pluginConfigs block.

Cart cookies expire after one year, by default. Change this with the carts.cartCookieDuration (opens new window) property:

return [
    'components' => [
        'plugins' => [
            'pluginConfigs' => [
                'commerce' => [
                    'components' => [
                        'carts' => [
                            'cartCookie' => [
                                // Add custom key-value cookie params
                            ],
                            // Set the cart expiry to one month
                            'cartCookieDuration' => 2629800,
                        ],
                    ],
                ],
            ],
        ],
    ],
];