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

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
Default value
'commerce/orders'
Defined by
Settings::$defaultView
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
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.

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

pdfAllowRemoteImages

Allowed types
boolean
Default value
false
Defined by
Settings::$pdfAllowRemoteImages

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

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. :::

Payments

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'

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 Cookie Configuration

Cart cookies expire after one year, by default. Change this with the carts.cartCookieDuration property:

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