cartflows / docs / wiki / WooCommerce-Integration.md

WooCommerce-Integration.md in CartFlows – Funnel Builder & Checkout Plugin for WooCommerce 3.0.1, at docs/wiki/WooCommerce-Integration.md

159 lines 6.2 KB

Raw Download Zip

1	# WooCommerce Integration
2
3	CartFlows is built on top of WooCommerce. It overrides WooCommerce checkout templates, hooks into the cart and order lifecycle, and adds product-level settings for funnel routing.
4
5	## Requirements
6
7	\| Requirement \| Minimum \| Tested Up To \|
8	\|-------------\|---------\|-------------\|
9	\| WooCommerce \| 3.0+ \| 9.8.5 \|
10
11	CartFlows checks for WooCommerce on activation and displays a notice if it is not installed or active.
12
13	## Template Overrides
14
15	CartFlows overrides WooCommerce templates placed in the `woocommerce/` directory. This follows the standard WooCommerce template override pattern — CartFlows templates take precedence over the active theme's WooCommerce templates.
16
17	```
18	cartflows/woocommerce/
19	├── checkout/
20	│ ├── form-checkout.php ← Main checkout form template
21	│ └── review-order.php ← Order review table
22	└── ...
23	```
24
25	CartFlows replaces the standard WooCommerce checkout with its own layout system (Modern Checkout, Instant Checkout, etc.) by replacing these template files.
26
27	## Checkout Page Replacement
28
29	When a visitor accesses a `cartflows_step` post of type `checkout`, CartFlows:
30
31	1. Detects the active page builder and loads the appropriate template
32	2. Enqueues checkout-specific scripts and styles
33	3. Fires `cartflows_checkout_scripts` for additional assets
34	4. Renders the checkout form via the WooCommerce `[woocommerce_checkout]` shortcode (or CartFlows equivalent)
35	5. Applies layout-specific CSS (Modern/Instant checkout styles)
36
37	## WooCommerce Hook Integration
38
39	CartFlows hooks into WooCommerce's standard hooks to control cart and order behaviour:
40
41	### Cart Management
42
43	```php
44	// Control which products are in the cart for a checkout step
45	add_filter( 'cartflows_selected_checkout_products', function( $products, $checkout_id ) {
46	return $products;
47	}, 10, 2 );
48	```
49
50	CartFlows can pre-populate the cart with specific products based on the checkout step configuration (`wcf-enable-product-options` meta).
51
52	### Post-Purchase Redirect
53
54	After a successful WooCommerce order:
55
56	1. CartFlows hooks into `woocommerce_thankyou` (or similar)
57	2. Checks if the order came through a CartFlows checkout step
58	3. Redirects to the configured next step (upsell, downsell, or thank you page)
59
60	The redirect target is filterable:
61
62	```php
63	add_filter( 'cartflows_checkout_next_step_id', function( $step_id, $order, $checkout_id ) {
64	return $step_id; // Modify to redirect elsewhere
65	}, 10, 3 );
66	```
67
68	### WooCommerce `wc_clean` Sanitiser
69
70	CartFlows uses `wc_clean()` for sanitising WooCommerce-specific data. This function handles:
71	- Strings: equivalent to `sanitize_text_field()`
72	- Arrays: recursively applies `wp_kses_post()` to values
73
74	It is registered as a custom sanitiser in `phpcs.xml.dist` so PHPCS recognises it.
75
76	## Checkout Layout Types
77
78	CartFlows supports multiple checkout layouts:
79
80	\| Layout \| Class \| Description \|
81	\|--------\|-------\|-------------\|
82	\| Standard \| `class-cartflows-checkout-markup.php` \| Default WooCommerce-style layout \|
83	\| Modern \| `layouts/class-cartflows-modern-checkout.php` \| Two-column modern layout \|
84	\| Instant \| `layouts/class-cartflows-instant-checkout.php` \| Full-screen distraction-free layout \|
85
86	The active layout is stored in step post meta (`wcf-checkout-layout`) and the template is resolved via the `cartflows_page_template` filter.
87
88	## Order Bump (Pre-Purchase Add-On)
89
90	An order bump is an additional product offered on the checkout page, typically displayed as a checkbox or highlighted box:
91
92	- Configured via step meta: `wcf-order-bump`
93	- Rendered within the checkout form
94	- Submits as an additional cart item
95	- Revenue tracked separately in analytics (`BumpOfferRevenue`, `BumpConversions`)
96
97	## Store Checkout (Global Checkout)
98
99	The Store Checkout feature (`modules/checkout/class-cartflows-global-checkout.php`) replaces the default WooCommerce checkout page with a CartFlows-designed checkout step:
100
101	- Enabled/disabled via `cartflows_update_store_checkout_status` AJAX
102	- Fires `cartflows_after_save_store_checkout` after status changes
103	- When enabled, all WooCommerce "Proceed to Checkout" buttons send customers through CartFlows
104
105	## WooCommerce Dynamic Flow
106
107	The WooCommerce Dynamic Flow module (`modules/woo-dynamic-flow/`) enables product-based automatic funnel routing:
108
109	- Each WooCommerce product can be assigned a CartFlows flow via the `cartflows_redirect_flow_id` product meta
110	- When that product is added to the cart and the customer proceeds to checkout, they are automatically redirected through the assigned funnel
111	- Shortcodes allow embedding flow links on product or category pages
112
113	## Product-Level CartFlows Settings
114
115	CartFlows adds a settings tab to each WooCommerce product edit page:
116
117	\| Setting \| Meta Key \| Description \|
118	\|---------\|----------\|-------------\|
119	\| Redirect to flow \| `cartflows_redirect_flow_id` \| Auto-redirect to funnel when this product is purchased \|
120	\| Custom button text \| `cartflows_add_to_cart_text` \| Override "Add to Cart" button text \|
121
122	## Checkout Field Management
123
124	CartFlows provides granular control over WooCommerce checkout fields:
125
126	- Enable/disable individual billing and shipping fields
127	- Set field width (full/half column)
128	- Customise labels and placeholders
129	- Set required/optional status
130
131	Field settings are stored as individual post meta keys on the checkout step (pattern: `wcf-{field_name}`).
132
133	## Analytics Integration
134
135	CartFlows tracks WooCommerce-specific metrics:
136
137	\| Metric \| Description \|
138	\|--------\|-------------\|
139	\| Conversion rate \| Orders / unique visitors to checkout \|
140	\| Revenue per visit \| Total revenue / total step visits \|
141	\| Average order value \| Total revenue / total orders \|
142	\| Offer conversions \| Upsell/downsell acceptance rate \|
143	\| Bump conversions \| Order bump acceptance rate \|
144
145	Tracking is done server-side using WooCommerce order data stored in post meta on CartFlows steps.
146
147	## Compatibility
148
149	CartFlows maintains compatibility with popular WooCommerce extensions via the `compatibilities/` directory. When a known conflicting plugin is detected, CartFlows applies targeted fixes.
150
151	See [](Page-Builder-IntegrationsPage-Builder-Integrations](Page-Builder-Integrations](Page-Builder-Integrations) for page builder compatibility.
152
153	## Related Pages
154
155	- [](Feature-ModulesFeature-Modules](Feature-Modules](Feature-Modules)
156	- [](Database-SchemaDatabase-Schema](Database-Schema](Database-Schema)
157	- [](WordPress-Hooks-ReferenceWordPress-Hooks-Reference](WordPress-Hooks-Reference](WordPress-Hooks-Reference)
158	- [](Architecture-OverviewArchitecture-Overview](Architecture-Overview](Architecture-Overview)
159