HOW TO MODIFY ORDERS USING HOOKS AND FILTERS IN WOOCOMMERCE

In some cases, it can be necessary to modify the data within an order before it is sent to ProfitMetrics. For example, in cases where a store is selling customisable products that vary in width or length, or in situations where the cost is only known after the order has been shipped. In order to support these scenarios, we have implemented overrides that can be used by developers to modify orders before they are sent to ProfitMetrics. These hooks provide a flexible way to extend and customize ProfitMetrics data.

Summary:

1. Execution Timing
The profitmetrics_api_order_line_items hook runs during the order payload building process, not immediately after order creation. Specifically, it executes when the plugin is preparing order data to send to the ProfitMetrics API.

2. Available Data
The hook receives three parameters:
- $line_items (array) - Processed line items array with structure: ['sku' => product_id, 'qty' => quantity, 'priceExVat' => unit_price]
- $order (WC_Order) - The complete WooCommerce order object
- $builder (OrderPayloadBuilder) - The payload builder instance

Note: The 'sku' field actually contains the product ID, not the SKU.

3. Use Case
This hook is intended for modifying line items before they sync with ProfitMetrics. It's a filter hook (apply_filters), not an action hook, meaning it expects you to return the modified $line_items array. You can use it to:
- Add custom fields to line items
- Filter out specific products
- Adjust pricing for analytics purposes
- Enrich product data before sync