HOW TO MODIFY ORDERS USING HOOKS 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 hooks 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

1. Modify line items before they're sent to the API

add_filter('profitmetrics_api_order_line_items', function($line_items, $order, $builder) {
    // Modify $line_items array
    return $line_items;
}, 10, 3);

2. Adjust calculated gross profit values

add_filter('profitmetrics_order_gross_profit', function($gross_profit, $order, $total_cost, $has_all_costs) {
    // Custom profit calculation logic
    return $gross_profit;
}, 10, 4);

3. Modify order weight calculations

add_filter('profitmetrics_order_weight_grams', function($order_weight, $order, $settings) {
    // Custom weight calculation
    return $order_weight;
}, 10, 3);

4. Override product cost retrieval

add_filter('profitmetrics_product_cost', function($cost, $product, $cost_source) {
    // Custom product cost logic
    return $cost;
}, 10, 3);

Use the new `profitmetrics_api_order_shipping_method` filter to modify shipping method names in exports. 
Add this to your theme's `functions.php`:

```php
// Simple shipping method renaming example
add_filter('profitmetrics_api_order_shipping_method', function($method, $order) {
    //Simple rename mapping
    $renamed = [
        'Free shipping' => 'FREE',
        'Flat rate'    => 'STANDARD',
        'Express'       => 'EXPRESS'
    ];
    return $renamed[$method] ?? $method;

    // Alternative: Use the order object to lookup order and shipping method and define your own logic
}, 10, 2);
```

**Common Use Cases**:  
- Standardize method names across carriers  
- Add store prefixes (`return 'STORE1-' . $method;`)  
- Append shipping class information