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',
];
# 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 should be defined on a per-environment basis.
- System Settings
- General Settings
- Email
- Status Email Address
- From Name
- Subscription Settings
- Billing detail update URL
- Email
- General Settings
# PHP Constants
# COMMERCE_PAYMENT_CURRENCY
This constant can be used to lock a valid payment currency ISO code, which otherwise defaults to the primary currency.
# Project Config
Craft Commerce stores the following items in the Craft project config:
- Commerce general settings
- Email settings
- PDF settings
- Gateways settings
- Order field layout
- Order Statuses
- Product types
- Fields and field groups
- Subscription field layout
Not everything should be stored in the project config. Some items are considered content, which will change in production—meaning they’re not stored in the project config:
- Discount promotions
- Sales promotions
- Shipping categories
- Shipping zones
- Shipping methods and rules
- Subscription plans
- Subscriptions elements
- Tax categories
- Tax zones
- Tax rates
- Order elements
- Products & Variant elements
# Config Settings
# System
# defaultView
- Allowed types
- string (opens new window)
- 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() (opens new window) for a list of supported value types.
# cartVariable
- Allowed types
- string (opens new window)
- Default value
'cart'
- Defined by
- Settings::$cartVariable
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
- 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
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
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
- 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
- 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
Whether to allow non-local images in generated order PDFs.
# updateBillingDetailsUrl
- Allowed types
- string (opens new window)
- Default value
''
- Defined by
- Settings::$updateBillingDetailsUrl
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
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
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
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
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,
],
],
],
],
],
],
];