Commerce Webform Order
Integrates Drupal Webform with Drupal Commerce, enabling the creation of commerce orders from webform submissions via a specialized webform handler.
commerce_webform_order
Install
composer require 'drupal/commerce_webform_order:^3.0'
Overview
Commerce Webform Order provides a powerful integration layer between Drupal's Webform and Commerce modules. It allows site builders to create complex order workflows by collecting customer data through webforms and automatically generating commerce orders from the submission data.
The module is particularly useful for donation forms, membership applications, service bookings, and any scenario where you need to collect detailed information from users while processing payments through Drupal Commerce's robust e-commerce system.
Unlike similar modules that sell webform submissions directly, Commerce Webform Order acts as a layer on top of Commerce, allowing you to sell any entity that implements PurchasableEntityInterface. This provides greater flexibility for complex e-commerce scenarios.
Features
- Webform handler that creates Commerce orders from webform submissions with extensive configuration options
- Payment Method webform element that embeds payment gateway selection forms directly into webforms
- Order State webform element that synchronizes and displays the current order state within webform submissions
- Payment Status webform element that tracks and displays payment status information
- Custom checkout pane (Payment Process) for handling payments initiated from webforms
- Automatic synchronization between order states/payment status and webform submission data
- Support for token values in handler configuration for dynamic order creation
- Cart behavior controls including empty cart, new cart, and combine cart options
- Option to redirect users to checkout after webform submission
- Support for setting order owner, billing profile, payment gateway, and payment method
- Order item field mapping to populate custom order item fields from webform data
- Prevention of webform submission updates when associated orders are no longer in draft state
- Debug mode for development and troubleshooting
- Alter hook for customizing orders, order items, and webform submissions before saving
Use Cases
Donation Form with Custom Amounts
Create a donation webform where users can enter custom donation amounts. Map a number field to the order item amount, allowing donors to specify their contribution. The handler creates an order with the custom price, and users are redirected to checkout for payment processing.
Event Registration with Payment
Build an event registration form that collects attendee information and creates a commerce order for the registration fee. Use the Order State element to display payment status on the confirmation page and trigger email notifications based on order completion.
Membership Application
Create a membership application form that collects member details and processes membership fees. Use the billing profile setting to pre-populate checkout with information collected in the form, streamlining the payment process.
Product Customization Form
Allow customers to customize products through a webform (e.g., engraving text, color selections) and map these values to order item custom fields. The order item stores the customization details alongside the standard commerce data.
Multi-Step Checkout Replacement
Replace Commerce's standard checkout flow with a webform-based checkout. Embed the Payment Method element to collect payment information directly in the form, then use the custom Payment Process checkout pane to handle the transaction.
Recurring Donation Setup
Create a donation form that collects payment method information for recurring donations. The Payment Method element supports stored payment methods, enabling future automated charges when integrated with Commerce recurring payment modules.
Tips
- Use token values (e.g., [webform_submission:values:amount]) in handler settings for dynamic order creation based on submission data.
- Add the :clear suffix to tokens (e.g., [current-user:name:clear]) to remove tokens that have no replacement value.
- When using the Payment Method element, replace the standard 'Payment process' checkout pane with 'Payment process (Commerce Webform Order)' and disable the 'Payment information' pane.
- Enable debugging during development to see detailed order creation information, but remember to disable it in production.
- Use the Order State and Payment Status elements to trigger conditional actions in other webform handlers based on commerce events.
- For anonymous donations, consider enabling 'Bypass access checks' for store access to avoid permission issues.
- The handler supports unlimited cardinality - add multiple handlers to create multiple order items from a single submission.
- Use YAML format in the 'Custom order data' field to add arbitrary data to orders that can be used by other modules or custom code.
Technical Details
Admin Pages 1
/admin/structure/webform/manage/{webform}/handlers/add/commerce_webform_order
Configuration form for adding the Commerce Webform Order handler to a webform. Allows setting up order creation rules and behavior.
Hooks 1
hook_commerce_webform_order_handler_postsave_alter
Alter the order, order item and webform submission in the webform handler before they are saved. Allows custom modifications to commerce entities created from webform submissions.
Security Notes 4
- The 'Bypass access checks' options should be used carefully as they override normal Drupal access controls.
- Debug mode displays order information to all users - only use in development environments.
- Payment method information is processed through Commerce Payment's secure APIs - no sensitive data is stored in webform submissions.
- The prevent_update feature helps maintain data integrity by blocking changes to submissions linked to completed orders.