commerce_free_sample

Commerce Free Sample lets store administrators offer customers a free product sample during checkout. When a qualifying order is placed, a dropdown appears on the order information step letting the customer choose one free sample from a curated list - which is then automatically added to their order as a line item. No coupon codes, no manual intervention: the entire flow is handled at checkout with zero extra steps for the customer.

This is useful for any Drupal Commerce store that wants to drive product discovery by letting buyers try something new with every purchase. You set up your pool of sample products once, define which orders are eligible, and the module handles the rest.

Features

• Checkout-integrated sample picker - A "Select a Free Sample" dropdown is embedded directly in the checkout sidebar on the Order Information step. Customers never leave the checkout flow.
• Curated sample pool - Administrators choose exactly which products are offered as samples. Only published free_sample-bundle products appear in the list, so drafts and discontinued products are never shown.
• Automatic order item management - When a sample is selected, it is added to the order as a standard line item (quantity 1, at whatever price is set on the variation - typically $0.00). Changing the selection removes the old sample and adds the new one atomically.
• Eligibility rules - The widget only appears for orders where all items have qualifying SKU suffixes (configurable in code). This lets you restrict free samples to specific product sizes, formats, or categories without writing custom logic.
• One sample per order - Enforced automatically; selecting a second sample replaces the first.
• Alphabetically sorted admin list - The settings form re-sorts the sample pool by product title on every save, keeping the customer-facing dropdown predictable.
• Clean install/uninstall - On enable, the module automatically wires the widget into the checkout entity form display. On uninstall, all field configuration is removed with no orphaned config left behind.

When would you use this module?

• A spice or food retailer wanting to introduce customers to new products
• A cosmetics or personal care store offering trial-size samples
• Any Drupal Commerce shop running a "try before you buy" or product discovery promotion

Post-Installation

1. Create your sample products

Before configuring the module, you need products of the free_sample bundle in Drupal Commerce. Create them at Commerce > Products > Add product and choose the Free Sample type. Set the variation price to $0.00 (or whatever your business requires).

2. Configure the sample pool

Navigate to Commerce > Free Samples (/admin/commerce/free-samples). Use the autocomplete fields to search for and add the products you want to offer. You can:

• Add as many products as needed using the "Add another product" button.
• Remove individual entries with the per-row "Remove" button.
• Save - the list is automatically de-duplicated, compacted, and sorted alphabetically by product title.

Any products you add here that are unpublished will be silently filtered out of the customer-facing dropdown until they are published.

3. Verify the checkout display

The module automatically configures the field_free_sample widget on the default Commerce order checkout form display (core.entity_form_display.commerce_order.default.checkout). To confirm or adjust placement, go to Commerce > Configuration > Order types > Default > Manage form display (Checkout mode).

4. Set eligibility rules (optional, requires code change)

By default, the sample picker only appears when all items in the cart have a field_sku_suffix value of 001, 003, 005, or 007. If your product variations use different SKU suffix conventions, edit the $allowed_suffixes array in commerce_free_sample_form_commerce_checkout_flow_multistep_default_alter() inside commerce_free_sample.module.

Additional Requirements

• Drupal Commerce (drupal/commerce) - core Commerce package
• Commerce Order (commerce_order) - Commerce sub-module, included with Drupal Commerce
• Commerce Checkout Order Fields (commerce_checkout_order_fields) - renders order fields in the checkout sidebar; this module places the widget inside that region

Your Commerce product catalog must include a free_sample product bundle/type. The module uses this bundle to identify which order items are samples and to filter the admin autocomplete.

Recommended modules/libraries

• Commerce Stock - Combine with free sample products to limit total sample inventory dispensed
• Commerce Promotion - Alternative approach: use promotions with "Buy X get Y free" rules for more complex eligibility logic; Commerce Free Sample is simpler and more direct for straightforward "one sample per order" use cases
• Commerce Cart - Already a dependency of Commerce Order; useful to review for customizing cart-level behaviors around free items

Similar projects

Module Difference Commerce Promotion (core Commerce) Handles "free item" via promotion rules. More powerful and configurable, but requires creating a promotion entity per campaign; does not offer a curated picker UX during checkout. Commerce Gift / Commerce Free Product (contrib) Add free products based on price thresholds or coupon codes. Commerce Free Sample instead gives the customer an explicit choice from a fixed pool, without requiring a code or meeting a price minimum. Commerce Add to Cart Extras Focuses on cart-page add-ons and upsells, not a checkout-step sample selection.

Commerce Free Sample is the right fit when you want customers to actively choose a sample from a specific product list, with eligibility controlled by what they are already buying — rather than by spend thresholds or coupon entry.

Community Documentation

• Drupal Commerce documentation
• Commerce Checkout documentation
• Single Directory Components (for theming the widget)

Additional Notes

Theming the widget

The sample picker renders as a standard <select> element inside the checkout sidebar. Override the widget output by implementing hook_field_widget_complete_WIDGET_TYPE_form_alter() with widget type free_sample_widget, or by adding CSS targeting .field--name-field-free-sample in your theme.

Pricing free samples at $0.00

Free sample product variations should be priced at $0.00 in Commerce. The module adds the variation to the order using $variation->getPrice(), so the price shown to the customer and charged at payment is whatever price you configure on the product.

Extending eligibility logic

The SKU suffix check in commerce_free_sample_form_commerce_checkout_flow_multistep_default_alter() is intentionally simple. For more complex eligibility (by product category, order total, customer role, etc.), implement your own hook_form_FORM_ID_alter() and set $form['sidebar']['order_fields:checkout']['field_free_sample']['#access'] accordingly.