Commerce Core
commerce
Drupal Commerce is the leading flexible eCommerce solution for Drupal, powering over 60,000 online stores of all sizes.
Overview
Drupal Commerce is a comprehensive, enterprise-grade eCommerce framework built on Drupal. It provides a complete solution for building online stores with support for products, orders, shopping carts, checkout flows, payments, promotions, taxes, and multi-store configurations.
The modular architecture allows site builders to enable only the components they need, while developers can extend functionality through a robust plugin system covering payment gateways, checkout panes, promotion offers, tax types, and more. The system uses event-driven architecture extensively, allowing modules to react to commerce events throughout the customer journey.
Key architectural features include: entity-based data model (Product, Order, Store, Payment), state machine integration for workflow management, price field type with multi-currency support, plugin-based extensibility, and comprehensive admin UI with dashboard metrics and activity logging.
Install
composer require 'drupal/commerce:^3.2'
Features
- Complete product catalog management with configurable product types, variations, and attributes for handling any product structure from simple items to complex configurable products
- Shopping cart system with session management for anonymous users, item combining, quantity updates, and cart expiration for abandoned carts
- Configurable multi-step checkout flows with customizable panes for login, billing information, order review, payment, and completion messages
- Extensible payment gateway architecture supporting on-site (direct card entry), off-site (redirect), and manual payment methods with stored payment method support
- Promotion and coupon system with flexible offer types (fixed amount, percentage, Buy X Get Y), condition-based targeting, usage limits, and date-based activation
- Tax calculation framework with built-in support for EU VAT, UK VAT, Canadian GST/HST, and custom tax zones with time-based rate changes
- Multi-store support with store-specific currencies, timezones, tax registrations, and billing country configurations
- Activity logging system tracking all commerce events including cart changes, order state transitions, and payment activities
- Sequential number pattern generation for order numbers with configurable reset strategies (infinite, yearly, monthly)
- Admin dashboard with metrics, inbox notifications, and quick access to commerce management functions
- Price field type with arbitrary precision arithmetic, multi-currency support, and locale-aware formatting
- Comprehensive event system allowing modules to hook into product, order, cart, checkout, payment, and promotion lifecycle events
Use Cases
Simple Online Store
Create a basic online store selling physical products. Enable Commerce Store, Product, Order, Cart, Checkout, and Payment modules. Create a store with your business details, add products with variations (sizes, colors), configure a checkout flow with billing information, and set up a payment gateway like PayPal or Stripe.
Multi-vendor Marketplace
Build a marketplace with multiple vendors using the multi-store architecture. Each vendor gets their own store entity with separate currencies, tax registrations, and payment configurations. Products are associated with specific stores, and the per-store number pattern sequences ensure unique order numbers per vendor.
Subscription Commerce
Implement recurring payments by extending Commerce with the Commerce Recurring module. Use stored payment methods to charge customers automatically, and create subscription product types with recurring billing periods.
B2B Commerce with Tax Exemptions
Configure EU VAT for business-to-business sales. Customers with valid VAT numbers receive zero-rated transactions for intra-community supplies. Use the tax number field on customer profiles and the EU VAT tax type's automatic VAT number validation.
Promotional Campaigns
Create complex promotional campaigns using the promotion system. Set up percentage discounts, fixed amount offers, or Buy X Get Y promotions. Target specific products using conditions, generate bulk coupon codes, set usage limits per customer, and schedule promotions with start/end dates.
Digital Downloads Store
Sell digital products by creating a product type without physical shipping requirements. Use the Commerce File module for secure download delivery after purchase, and configure instant checkout completion for immediate access.
Tips
- Use the Commerce Dashboard at /admin/commerce for quick access to orders, products, and configuration
- Partner banners can be disabled by adding $settings['commerce_show_partner_banners'] = FALSE; to settings.php
- Product variations support automatic title generation from attribute values - enable this in variation type settings
- The promotion system supports compatibility rules - set promotions to 'Cannot be combined' to prevent stacking
- Use the activity log at /admin/commerce/orders/{order}/logs to audit all changes to an order
- Cart expiration can be configured per order type to automatically clean up abandoned carts
- The price resolver chain allows custom pricing logic - add custom resolvers at higher priority to override default prices
- Checkout flows can be customized per order type using third-party settings on the order type entity
Dependencies
Related Projects
Provides address field type used for store addresses, billing profiles, and shipping addresses
Provides entity form and display management, bundle plugins, and entity permissions
Provides workflow and state management for orders with configurable transitions
Provides customer profile entities for billing and shipping addresses
Provides inline editing of referenced entities like product variations
Provides token replacement in checkout completion messages, receipts, and number patterns
Provides administrative views for products, orders, promotions, and other Commerce entities
Optional integration for shipping rates and fulfillment workflows
Optional integration for physical product dimensions and weights
Optional integration for generating PDF invoices and packing slips
Admin Pages
| Title | Path | Description |
|---|---|---|
| Commerce | /admin/commerce |
Main Commerce administration dashboard providing quick access to all Commerce functionality, metrics overview, and inbox notifications from Drupal Commerce. |
| Configuration | /admin/commerce/config |
Overview page for all Commerce configuration options organized by category. |
| Stores | /admin/commerce/config/stores |
Manage your store entities. Each store has its own name, email, default currency, timezone, address, and billing countries configuration. |
| Store types | /admin/commerce/config/store-types |
Manage store type bundles and their field configurations. |
| Currencies | /admin/commerce/config/currencies |
Manage currencies available in your store. Import from the commerceguys/intl library or create custom currencies. |
| Products | /admin/commerce/products |
Manage your product catalog. Create, edit, duplicate, and delete products with their variations. |
| Product types | /admin/commerce/config/product-types |
Manage product type bundles including variation types association, multiple variations setting, and variation field injection. |
| Product variation types | /admin/commerce/config/product-variation-types |
Manage product variation type bundles including order item type association and title generation settings. |
| Product attributes | /admin/commerce/product-attributes |
Manage product attributes (like Color, Size) and their values. Attributes are used to create product variations. |
| Orders | /admin/commerce/orders |
View and manage customer orders including order status, payments, and fulfillment. |
| Order types | /admin/commerce/config/order-types |
Manage order type bundles including workflow selection, refresh settings, and receipt email configuration. |
| Order item types | /admin/commerce/config/order-item-types |
Manage order item type bundles and their purchasable entity type association. |
| Checkout flows | /admin/commerce/config/checkout-flows |
Manage checkout flow configurations with customizable steps and panes for the customer checkout experience. |
| Payment gateways | /admin/commerce/config/payment-gateways |
Configure payment gateways for processing customer payments including on-site, off-site, and manual gateways. |
| Promotions | /admin/commerce/promotions |
Manage promotions and discounts with configurable offers, conditions, coupons, and usage limits. |
| Tax types | /admin/commerce/config/tax-types |
Configure tax types for automatic tax calculation including EU VAT, UK VAT, Canadian sales tax, and custom tax zones. |
| Number patterns | /admin/commerce/config/number-patterns |
Configure sequential number patterns for generating order numbers and similar sequences. |
Permissions
| Permission | Description |
|---|---|
|
Grants access to the main Commerce admin area and dashboard |
|
Create, edit, and delete store entities |
|
Maintain store types and their associated fields |
|
Create, edit, and delete currency configurations |
|
Create, edit, and delete products |
|
Maintain product types and their associated fields |
|
Translate any product attribute values |
|
View, create, edit, and delete orders |
|
Maintain order types and their associated fields |
|
Reassign orders from one customer to another |
|
Unlock orders that have been locked |
|
Complete a purchase through the checkout form |
|
Create, edit, and delete checkout flow configurations |
|
Create, edit, and delete payment gateway configurations |
|
View and manage payments on orders |
|
Create, edit, and delete promotions |
|
Generate multiple coupons at once for promotions |
|
Create, edit, and delete tax type configurations |
|
Create, edit, and delete number pattern configurations |
Hooks
| Hook | Description |
|---|---|
hook_commerce_inline_form_alter |
Perform alterations before a Commerce inline form is rendered |
hook_commerce_inline_form_PLUGIN_ID_alter |
Perform plugin-specific inline form alterations |
Troubleshooting
Ensure PHP sessions are working correctly. Commerce stores anonymous cart IDs in the session. Check session configuration and ensure the session cookie is being set properly.
Check the currency configuration at /admin/commerce/config/currencies. Each currency has a 'Fraction digits' setting that controls decimal precision.
Verify the promotion is enabled, within date range, has available usage, and conditions match the order. Check store and order type restrictions on the promotion.
Ensure a tax type is configured at /admin/commerce/config/tax-types and its conditions match your orders. For EU VAT, verify the store has tax registrations set for applicable countries.
The payment step is hidden when the order balance is zero. Verify products have prices and promotions aren't making the order free.
Ensure a number pattern is configured and assigned to the order type at /admin/commerce/config/order-types. Check that the number pattern's target entity type is set to 'commerce_order'.
Security Notes
- Payment gateway credentials are stored in configuration - use environment variables or key module for production
- Cart session IDs are stored in PHP sessions - ensure session security is properly configured
- Admin permissions should be granted carefully - 'administer commerce_order' allows viewing all customer data
- Payment method storage includes sensitive card data (last 4 digits, expiration) - ensure database security
- Coupon codes are case-insensitive and stored in the database - use sufficient length and complexity for bulk-generated codes