Craft Commerce

To install Craft Commerce using Composer, navigate to your project directory, require the package, and then run the Craft plugin installation command. You can optionally copy the provided example templates to your project's templates folder to jumpstart your development.

# go to the project directory
cd /path/to/my-project.test

# tell Composer to load the plugin
composer require craftcms/commerce

# tell Craft to install the plugin
php craft plugin/install commerce

# optional: copy the Craft Commerce example templates to your project
templates folder
php craft commerce/example-templates

You can install Craft Commerce directly through the Craft CMS Control Panel:

1. Navigate to the Plugin Store in your Control Panel.
2. Search for "Commerce".
3. Click the Install button in the plugin's modal window.

The Tax adjuster manages two main scenarios for tax calculation:

1. Adding Tax: If a TaxRate is applicable to the order's address/zone and is not marked as 'included', the adjuster creates an OrderAdjustment of type tax to add the tax amount to the order or line items.

2. Removing Included Tax: If a TaxRate is marked as include (tax is already part of the price) but the customer provides a valid Tax ID (e.g., for EU VAT purposes) or the rate is configured to removeIncluded, the adjuster creates a discount type adjustment. This effectively subtracts the tax portion from the price so the customer is not overcharged.

Tax rates can be applied at the Order level (e.g., TAXABLE_ORDER_TOTAL_PRICE or TAXABLE_ORDER_TOTAL_SHIPPING) or at the Line Item level (e.g., TAXABLE_PURCHASABLE).

The Donation element is a specialized type of Purchasable used for processing non-physical, non-inventory donations. Unlike standard products, donations do not have inventory, are not shippable, and are not taxable.

When adding a donation to a cart, you must provide a donationAmount within the line item options. The Donation element uses this amount to set the line item's price via populateLineItem() and validates that the amount is numeric and greater than zero via getLineItemRules().

The HasPurchasableConditionRule allows you to filter orders based on whether they contain specific types of purchasable elements. By default, it filters for craft\commerce\elements\Variant types.

You can customize this rule by setting the purchasableType property to a different purchasable element class.

Available purchasable types are dynamically retrieved from the Commerce plugin's purchasable element types registry.

// Example of configuring the rule with a custom purchasable type
// Note: This is typically handled via the Craft Control Panel UI or when defining custom element conditions in code.
$rule = new \craft\commerce\elements\conditions\orders\HasPurchasableConditionRule();
$rule->purchasableType = SomeCustomPurchasableElement::class;

When developing the Commerce UI locally, use these environment variables to configure the development server's public URL, port, and loopback address. These settings are typically used to ensure the UI can communicate correctly with the Craft CMS backend and assets during local development (e.g., in a Docker environment).

DEV_SERVER_PUBLIC="http://localhost:8082/"
DEV_SERVER_PORT="8082"
DEV_SERVER_LOOPBACK="http://host.docker.internal:8082"

The CRAFT_ASSETS_PATH environment variable defines the relative path to the Craft CMS assets directory. This is required in the current development setup to allow the Commerce UI to directly include components from the craftcms/cms repository before they are unified into a monorepo or separate package.

CRAFT_ASSETS_PATH='./../../../../../cms/src/web/assets/'

If a subscription is active, you can use getAlternativePlans() to find other plans available through the same gateway that the user can switch to. This method checks if the plans are compatible using the plan's canSwitchFrom() method.

$alternativePlans = $subscription->getAlternativePlans();

foreach ($alternativePlans as $plan) {
    // Display available upgrade/downgrade options
    echo $plan->name;
}

You can retrieve Donation elements using the find() method, which returns a DonationQuery instance. This allows you to filter and retrieve donations using the standard Craft Element Query interface.

$donations = craft\commerce\elements\Donation::find()
    ->enabled()
    ->all();