# Hooks & Filters Reference

This document lists all custom action hooks and filter hooks introduced by the **Faire for WooCommerce** plugin. Use these hooks to extend or customize the plugin's behavior in your own plugins or themes.

---

## Table of Contents

- [Plugin Lifecycle](#plugin-lifecycle) (3 action hooks)
- [Product Sync](#product-sync) (25 filter hooks)
- [Product Linking](#product-linking) (3 filter hooks)
- [Orders](#orders) (3 filter hooks)
- [WPML Integration](#wpml-integration) (2 filter hooks)
- [Settings & Utilities](#settings--utilities) (3 filter hooks)

---

## Plugin Lifecycle

### `faire_for_woocommerce_loaded`

Fires after the Faire for WooCommerce plugin has been loaded. Use this hook to perform additional actions or register functionality that depends on the plugin.

| Parameter | Type | Description |
|-----------|------|-------------|
| — | — | No parameters. |

**Since:** 1.0.0
**Source:** [`src/class-faire.php:121`](src/class-faire.php#L121)

<details>
<summary>Example</summary>

```php
add_action( 'faire_for_woocommerce_loaded', function () {
    // The Faire for WooCommerce plugin is now loaded.
    // Register your dependent functionality here.
} );
```
</details>

---

### `before_faire_for_woocommerce_init`

Fires before the Faire for WooCommerce plugin has been fully initialized. Use this hook to perform setup tasks that must run before the plugin completes initialization.

| Parameter | Type | Description |
|-----------|------|-------------|
| — | — | No parameters. |

**Since:** 1.0.0
**Source:** [`src/class-faire.php:180`](src/class-faire.php#L180)

<details>
<summary>Example</summary>

```php
add_action( 'before_faire_for_woocommerce_init', function () {
    // Runs before Faire for WooCommerce initializes its classes.
} );
```
</details>

---

### `faire_for_woocommerce_init`

Fires after the Faire for WooCommerce plugin has been fully initialized. Use this hook to perform additional initialization or setup tasks that depend on the plugin's classes being ready.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$faire` | `array` | An array containing the initialized Faire-related classes. |

**Since:** 1.0.0
**Source:** [`src/class-faire.php:219`](src/class-faire.php#L219)

<details>
<summary>Example</summary>

```php
add_action( 'faire_for_woocommerce_init', function ( array $faire ) {
    // Access initialized classes, e.g. $faire['Sync_Product'].
}, 10, 1 );
```
</details>

---

## Product Sync

### `faire_wc_products_admin_column_sync`

Filters the HTML output of the Faire product sync column in the WooCommerce admin products list.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$output_column` | `string` | The HTML output for the column. |
| `$id` | `int` | The product ID. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:237`](src/sync/class-sync-product.php#L237)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_products_admin_column_sync', function ( string $output_column, int $id ): string {
    // Append custom info to the sync column.
    $output_column .= '<br><em>Custom note</em>';
    return $output_column;
}, 10, 2 );
```
</details>

---

### `faire_wc_products_admin_column_lifecycle`

Filters the HTML output of the Faire product lifecycle column in the WooCommerce admin products list.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$output_column` | `string` | The HTML output for the column. |
| `$id` | `int` | The product ID. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:262`](src/sync/class-sync-product.php#L262)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_products_admin_column_lifecycle', function ( string $output_column, int $id ): string {
    // Override the lifecycle column output.
    return '<span class="custom-lifecycle">' . esc_html( $output_column ) . '</span>';
}, 10, 2 );
```
</details>

---

### `faire_wc_product_description`

Filters the product description before it is sent to Faire during sync.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$description` | `string` | The stripped product description. |
| `$product` | `\WC_Product` | The WooCommerce product. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2266`](src/sync/class-sync-product.php#L2266)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_description', function ( string $description, \WC_Product $product ): string {
    // Append a disclaimer to all product descriptions synced to Faire.
    return $description . "\n\nWholesale only.";
}, 10, 2 );
```
</details>

---

### `faire_wc_product_short_description`

Filters the product short description before it is sent to Faire during sync.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$short_description` | `string` | The stripped product short description. |
| `$product` | `\WC_Product` | The WooCommerce product. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2256`](src/sync/class-sync-product.php#L2256)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_short_description', function ( string $short_description, \WC_Product $product ): string {
    // Limit the short description to 100 characters.
    return mb_substr( $short_description, 0, 100 );
}, 10, 2 );
```
</details>

---

### `faire_wc_product_set_product_args`

Filters the full array of product arguments before they are sent to the Faire API for create/update operations.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$args` | `array` | The product arguments array. |
| `$product` | `\WC_Product` | The WooCommerce product. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2326`](src/sync/class-sync-product.php#L2326)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_set_product_args', function ( array $args, \WC_Product $product ): array {
    // Add a custom tag to the product args.
    $args['tags'] = array( 'custom-tag' );
    return $args;
}, 10, 2 );
```
</details>

---

### `faire_wc_product_is_discontinued`

Filters whether a product or variation is marked as discontinued when syncing inventory to Faire.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$is_discontinued` | `bool` | Whether the product is discontinued. Default `false`. |
| `$product` | `\WC_Product` | The WooCommerce product or variation. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2347`](src/sync/class-sync-product.php#L2347) (also used at lines 2369, 2377, 2392, 2400)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_is_discontinued', function ( bool $is_discontinued, \WC_Product $product ): bool {
    // Mark products in the "archive" category as discontinued.
    if ( has_term( 'archive', 'product_cat', $product->get_id() ) ) {
        return true;
    }
    return $is_discontinued;
}, 10, 2 );
```
</details>

---

### `faire_wc_product_set_product_inventories_args`

Filters the product inventory arguments array before it is sent to the Faire API for inventory updates.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$args` | `array` | The inventory arguments array. |
| `$product` | `\WC_Product` | The WooCommerce product. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2412`](src/sync/class-sync-product.php#L2412)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_set_product_inventories_args', function ( array $args, \WC_Product $product ): array {
    // Override inventory quantities for a specific product.
    foreach ( $args as &$variant_args ) {
        if ( isset( $variant_args['current_quantity'] ) ) {
            $variant_args['current_quantity'] = max( 0, $variant_args['current_quantity'] - 5 );
        }
    }
    return $args;
}, 10, 2 );
```
</details>

---

### `faire_wc_product_stock_quantity`

Filters the stock quantity for a product or variation before it is sent to Faire.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$stock_quantity` | `int\|null` | The stock quantity, or `null` if stock is not managed. |
| `$product` | `\WC_Product` | The WooCommerce product or variation. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2585`](src/sync/class-sync-product.php#L2585)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_stock_quantity', function ( ?int $stock_quantity, \WC_Product $product ): ?int {
    // Reserve 2 units from Faire stock.
    if ( null !== $stock_quantity ) {
        return max( 0, $stock_quantity - 2 );
    }
    return $stock_quantity;
}, 10, 2 );
```
</details>

---

### `faire_wc_product_unit_multiplier`

Filters the case/unit multiplier for a product before it is sent to Faire.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$unit_multiplier` | `string\|int` | The unit multiplier value. Default `1`. |
| `$product` | `\WC_Product` | The WooCommerce product or variation. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2596`](src/sync/class-sync-product.php#L2596)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_unit_multiplier', function ( $unit_multiplier, \WC_Product $product ) {
    // Force a unit multiplier of 6 for products in a specific category.
    if ( has_term( 'wholesale-pack', 'product_cat', $product->get_id() ) ) {
        return 6;
    }
    return $unit_multiplier;
}, 10, 2 );
```
</details>

---

### `faire_wc_product_minimum_order_quantity`

Filters the minimum order quantity for a product before it is sent to Faire.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$minimum_order_quantity` | `string\|int` | The minimum order quantity. Default `1`. |
| `$product` | `\WC_Product` | The WooCommerce product or variation. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2607`](src/sync/class-sync-product.php#L2607)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_minimum_order_quantity', function ( $minimum_order_quantity, \WC_Product $product ) {
    // Set a minimum order quantity of 12 for all products.
    return 12;
}, 10, 2 );
```
</details>

---

### `faire_wc_product_per_style_minimum_order_quantity`

Filters the per-style minimum order quantity for a product before it is sent to Faire.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$per_style_minimum_order_quantity` | `string\|int` | The per-style minimum order quantity. Default `0`. |
| `$product` | `\WC_Product` | The WooCommerce product or variation. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2618`](src/sync/class-sync-product.php#L2618)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_per_style_minimum_order_quantity', function ( $qty, \WC_Product $product ) {
    return 3;
}, 10, 2 );
```
</details>

---

### `faire_wc_product_currency`

Filters the currency code for a product before it is sent to Faire.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$currency` | `string` | The WooCommerce currency code (e.g. `USD`). |
| `$product` | `\WC_Product` | The WooCommerce product or variation. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2628`](src/sync/class-sync-product.php#L2628)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_currency', function ( string $currency, \WC_Product $product ): string {
    // Always sync products to Faire in USD.
    return 'USD';
}, 10, 2 );
```
</details>

---

### `faire_wc_product_price_geo_constraint`

Filters the price geo constraint (country or country group) for a product before it is sent to Faire.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$geo_constraint` | `string` | The geo constraint value. |
| `$product` | `\WC_Product` | The WooCommerce product or variation. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2638`](src/sync/class-sync-product.php#L2638)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_price_geo_constraint', function ( string $geo_constraint, \WC_Product $product ): string {
    // Override the geo constraint for specific products.
    return 'US';
}, 10, 2 );
```
</details>

---

### `faire_wc_product_allow_sales_when_out_of_stock`

Filters whether a product allows sales when out of stock (backorders) on Faire.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$allow_backorders` | `bool` | Whether backorders are allowed. Inherits from the WooCommerce product setting. |
| `$product` | `\WC_Product` | The WooCommerce product or variation. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2649`](src/sync/class-sync-product.php#L2649)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_allow_sales_when_out_of_stock', function ( bool $allow, \WC_Product $product ): bool {
    // Disable backorders on Faire for all products.
    return false;
}, 10, 2 );
```
</details>

---

### `faire_wc_product_wholesale_price`

Filters the wholesale price for a product before it is sent to Faire.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$wholesale_price` | `float\|string` | The wholesale price. |
| `$product` | `\WC_Product` | The WooCommerce product or variation. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2683`](src/sync/class-sync-product.php#L2683)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_wholesale_price', function ( $wholesale_price, \WC_Product $product ) {
    // Apply a 10% discount to the wholesale price.
    return (float) $wholesale_price * 0.9;
}, 10, 2 );
```
</details>

---

### `faire_wc_product_retail_price`

Filters the retail (MSRP) price for a product before it is sent to Faire.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$retail_price` | `float\|string` | The retail price. |
| `$product` | `\WC_Product` | The WooCommerce product or variation. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2720`](src/sync/class-sync-product.php#L2720)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_retail_price', function ( $retail_price, \WC_Product $product ) {
    // Round the retail price to the nearest dollar.
    return round( (float) $retail_price );
}, 10, 2 );
```
</details>

---

### `faire_wc_product_tariff_code`

Filters the tariff/HS code for a product before it is sent to Faire.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$tariff_code` | `string` | The tariff code. |
| `$product` | `\WC_Product` | The WooCommerce product or variation. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2737`](src/sync/class-sync-product.php#L2737)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_tariff_code', function ( string $tariff_code, \WC_Product $product ): string {
    // Set a default tariff code if none is configured.
    return $tariff_code ?: '6911.10.0000';
}, 10, 2 );
```
</details>

---

### `faire_wc_product_preorderable`

Filters whether a product is marked as preorderable on Faire.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$preorderable` | `bool` | Whether the product is preorderable. |
| `$product` | `\WC_Product` | The WooCommerce product. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2749`](src/sync/class-sync-product.php#L2749)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_preorderable', function ( bool $preorderable, \WC_Product $product ): bool {
    // Disable preorders for all products.
    return false;
}, 10, 2 );
```
</details>

---

### `faire_wc_product_preorder_details`

Filters the preorder details array for a product before it is sent to Faire.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$preorder_details` | `array` | Preorder details with keys: `order_by_date`, `keep_active_past_order_by_date`, `expected_ship_date`, `expected_ship_window_end_date`. |
| `$product` | `\WC_Product` | The WooCommerce product. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2764`](src/sync/class-sync-product.php#L2764)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_preorder_details', function ( array $details, \WC_Product $product ): array {
    // Override the expected ship date.
    $details['expected_ship_date'] = '2025-06-01';
    return $details;
}, 10, 2 );
```
</details>

---

### `faire_wc_product_taxonomy_type`

Filters the Faire taxonomy type for a product before it is sent to Faire.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$taxonomy_type` | `string` | The taxonomy type value. |
| `$product` | `\WC_Product` | The WooCommerce product. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2776`](src/sync/class-sync-product.php#L2776)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_taxonomy_type', function ( string $taxonomy_type, \WC_Product $product ): string {
    // Map WooCommerce categories to Faire taxonomy types.
    if ( has_term( 'candles', 'product_cat', $product->get_id() ) ) {
        return 'home_decor_candles';
    }
    return $taxonomy_type;
}, 10, 2 );
```
</details>

---

### `faire_wc_product_backordered_until_default`

> **Note:** This hook is currently **commented out** in the source code and is not active. It is documented here for reference in case it is enabled in a future release.

Filters the default backordered-until date when a product has an "on backorder" stock status.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$backordered_until` | `string` | ISO 8601 date string. Default: 5 years from now. |
| `$product` | `\WC_Product` | The WooCommerce product. |

**Source:** [`src/sync/class-sync-product.php:2792`](src/sync/class-sync-product.php#L2792) (commented out)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_backordered_until_default', function ( string $date, \WC_Product $product ): string {
    // Set the default backorder date to 6 months from now.
    return date( 'c', strtotime( '+6 months' ) );
}, 10, 2 );
```
</details>

---

### `faire_wc_product_backordered_until`

Filters the backordered-until date for a product before it is sent to Faire.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$backordered_until` | `string\|null` | ISO 8601 date string, or `null`. |
| `$product` | `\WC_Product` | The WooCommerce product. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2796`](src/sync/class-sync-product.php#L2796)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_backordered_until', function ( ?string $date, \WC_Product $product ): ?string {
    // Set a backorder date for out-of-stock products.
    if ( 'outofstock' === $product->get_stock_status() ) {
        return date( 'c', strtotime( '+3 months' ) );
    }
    return $date;
}, 10, 2 );
```
</details>

---

### `faire_wc_product_measurements`

Filters the measurements object (weight, dimensions) for a product before it is sent to Faire.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$measurements` | `object\|false` | An object with properties: `mass_unit`, `weight`, `distance_unit`, `length`, `width`, `height`. `false` if no measurements are set. |
| `$product` | `\WC_Product` | The WooCommerce product. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2854`](src/sync/class-sync-product.php#L2854)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_measurements', function ( $measurements, \WC_Product $product ) {
    // Add default measurements if none are set.
    if ( false === $measurements ) {
        $measurements = (object) array(
            'mass_unit' => 'POUNDS',
            'weight'    => '1.0',
        );
    }
    return $measurements;
}, 10, 2 );
```
</details>

---

### `faire_wc_product_lifecycle_state_default`

Filters the default lifecycle state assigned to a product when no lifecycle state meta is set.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$lifecycle_state` | `string` | The default lifecycle state (from `Sync_Product::DEFAULT_FAIRE_LIFECYCLE_STATE`). |
| `$product` | `\WC_Product` | The WooCommerce product. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2875`](src/sync/class-sync-product.php#L2875)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_lifecycle_state_default', function ( string $state, \WC_Product $product ): string {
    // Default new products to "PUBLISHED" instead of the plugin default.
    return 'PUBLISHED';
}, 10, 2 );
```
</details>

---

### `faire_wc_product_lifecycle_state`

Filters the final lifecycle state for a product before it is sent to Faire. This runs after `faire_wc_product_lifecycle_state_default` has been applied.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$lifecycle_state` | `string` | The lifecycle state (e.g. `PUBLISHED`, `UNPUBLISHED`, `DISCONTINUED`). |
| `$product` | `\WC_Product` | The WooCommerce product. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2878`](src/sync/class-sync-product.php#L2878)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_lifecycle_state', function ( string $state, \WC_Product $product ): string {
    // Force draft products to be unpublished on Faire.
    if ( 'draft' === $product->get_status() ) {
        return 'UNPUBLISHED';
    }
    return $state;
}, 10, 2 );
```
</details>

---

### `faire_wc_product_excluded_product_sync_args`

Filters the list of excluded product sync argument keys. Fields in this list are stripped from the sync payload.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$excluded_args` | `array` | Array of excluded argument keys (e.g. `product.preorderable`). |
| `$excluded_setting` | `array` | The raw excluded fields setting. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2572`](src/sync/class-sync-product.php#L2572)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_excluded_product_sync_args', function ( array $excluded_args, array $excluded_setting ): array {
    // Also exclude measurements from syncing.
    $excluded_args[] = 'product.measurements';
    return $excluded_args;
}, 10, 2 );
```
</details>

---

### `faire_wc_product_is_sync_allowed`

Filters whether a specific WooCommerce product is allowed to sync to Faire. By default, grouped and external products are excluded.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$allowed` | `bool` | Whether the product is allowed to sync. |
| `$id` | `int` | The product ID. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product.php:2975`](src/sync/class-sync-product.php#L2975)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_product_is_sync_allowed', function ( bool $allowed, int $id ): bool {
    // Prevent products in the "internal" category from syncing.
    if ( has_term( 'internal', 'product_cat', $id ) ) {
        return false;
    }
    return $allowed;
}, 10, 2 );
```
</details>

---

## Product Linking

### `faire_wc_linking_create_product_csv_rows`

Filters the CSV rows generated for a Faire product during the product linking/import process.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$rows` | `array` | The array of CSV row arrays for the product (including variant rows for variable products). |
| `$faire_product` | `object` | The Faire product object. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product-linking.php:1057`](src/sync/class-sync-product-linking.php#L1057)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_linking_create_product_csv_rows', function ( array $rows, object $faire_product ): array {
    // Add a custom meta column to all product rows.
    foreach ( $rows as &$row ) {
        $row['Meta: _custom_faire_field'] = $faire_product->id ?? '';
    }
    return $rows;
}, 10, 2 );
```
</details>

---

### `faire_wc_linking_create_variant_csv_rows`

Filters the CSV row generated for a single Faire variant during the product linking/import process.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$row` | `array` | The CSV row array for the variant. |
| `$faire_variant` | `object` | The Faire variant object. |
| `$faire_product` | `object` | The parent Faire product object. |
| `$parent_col_match` | `array` | The parent product's SKU column match value. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product-linking.php:1258`](src/sync/class-sync-product-linking.php#L1258)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_linking_create_variant_csv_rows', function ( array $row, object $faire_variant, object $faire_product, $parent_col_match ): array {
    // Override the variant weight.
    if ( isset( $faire_variant->measurements->weight ) ) {
        $row['Weight (kg)'] = $faire_variant->measurements->weight;
    }
    return $row;
}, 10, 4 );
```
</details>

---

### `faire_wc_get_product_ids_by_sku`

Filters the array of WooCommerce product IDs returned when looking up products by SKU during the linking process.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$ids` | `array` | The array of product IDs matching the SKU. |
| `$sku` | `string` | The product SKU being looked up. |

**Since:** 1.0.0
**Source:** [`src/sync/class-sync-product-linking.php:2325`](src/sync/class-sync-product-linking.php#L2325)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_get_product_ids_by_sku', function ( array $ids, string $sku ): array {
    // Add a custom product ID lookup for a legacy SKU format.
    if ( str_starts_with( $sku, 'LEGACY-' ) ) {
        $legacy_id = my_legacy_sku_lookup( $sku );
        if ( $legacy_id ) {
            $ids[] = $legacy_id;
        }
    }
    return $ids;
}, 10, 2 );
```
</details>

---

## Orders

### `faire_add_to_order_product`

Filters the product data array before it is added as a line item to a WooCommerce order during Faire order import.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$product` | `array` | The product data array to be added to the order. |

**Since:** 1.0.0
**Source:** [`src/woocommerce/class-order.php:300`](src/woocommerce/class-order.php#L300)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_add_to_order_product', function ( array $product ): array {
    // Modify the product data before adding to the WC order.
    return $product;
} );
```
</details>

---

### `faire_wc_order_update_status`

Filters whether to proceed with a WooCommerce order status update triggered by a Faire order state change. Return `false` to suppress the status update.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$should_update` | `bool` | Whether to proceed with the status update. Default `true`. |
| `$wc_order` | `\WC_Order` | The WooCommerce order. |
| `$mapped_status` | `string` | The new WooCommerce order status. |
| `$faire_status` | `string` | The Faire order status. |

**Since:** 1.7.4
**Source:** [`src/woocommerce/class-order.php:535`](src/woocommerce/class-order.php#L535), [`src/woocommerce/class-order.php:584`](src/woocommerce/class-order.php#L584), [`src/admin/order/class-order.php:380`](src/admin/order/class-order.php#L380)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_order_update_status', function ( bool $should_update, \WC_Order $wc_order, string $mapped_status, string $faire_status ): bool {
    // Prevent Faire from setting orders to "cancelled" status.
    if ( 'cancelled' === $mapped_status ) {
        return false;
    }
    return $should_update;
}, 10, 4 );
```
</details>

---

### `faire_to_wc_order_status`

Filters the mapped WooCommerce order status that corresponds to a given Faire order status. Use this to customize the status mapping.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$mapped_status` | `string` | The mapped WooCommerce order status. |
| `$order_status_mapping` | `array` | The full status mapping array (Faire status => WC status). |
| `$faire_order_status` | `string` | The original Faire order status. |

**Since:** 1.7.4
**Source:** [`src/faire/class-order-status.php:54`](src/faire/class-order-status.php#L54)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_to_wc_order_status', function ( string $mapped_status, array $mapping, string $faire_status ): string {
    // Map Faire "processing" orders to a custom WC status.
    if ( 'processing' === $faire_status ) {
        return 'wc-faire-processing';
    }
    return $mapped_status;
}, 10, 3 );
```
</details>

---

## WPML Integration

### `faire_wc_wpml_enabled_languages`

Filters the array of language codes that are enabled for Faire product sync when using WPML.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$languages` | `array` | An array of two-letter language codes. |

**Since:** 1.0.0
**Source:** [`src/wpml/class-wpml-product.php:78`](src/wpml/class-wpml-product.php#L78)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_wpml_enabled_languages', function ( array $languages ): array {
    // Only sync English and French products to Faire.
    return array( 'en', 'fr' );
} );
```
</details>

---

### `faire_wc_wpml_enabled_product`

Filters whether a specific product is enabled for Faire sync based on its WPML language.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$enabled` | `bool` | Whether the product is enabled for Faire sync. |
| `$id` | `int` | The product ID. |

**Since:** 1.0.0
**Source:** [`src/wpml/class-wpml-product.php:109`](src/wpml/class-wpml-product.php#L109)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_wpml_enabled_product', function ( bool $enabled, int $id ): bool {
    // Always allow a specific product to sync regardless of language.
    if ( 42 === $id ) {
        return true;
    }
    return $enabled;
}, 10, 2 );
```
</details>

---

## Settings & Utilities

### `faire_wc_suppress_currency_matching`

Filters whether to suppress the currency matching validation between WooCommerce and Faire. Return `true` to bypass the currency check.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$suppress` | `bool` | Whether to suppress currency matching. Default `false`. |

**Since:** 1.0.0
**Source:** [`src/admin/class-settings.php:625`](src/admin/class-settings.php#L625)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_suppress_currency_matching', '__return_true' );
```
</details>

---

### `faire_for_woocommerce_template_path`

Filters the template path used by the plugin for locating template files.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$template_path` | `string` | The template path. Default `plugin-name/`. |

**Since:** 1.0.0
**Source:** [`src/class-utils.php:73`](src/class-utils.php#L73)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_for_woocommerce_template_path', function ( string $path ): string {
    return 'my-theme/faire/';
} );
```
</details>

---

### `faire_wc_country_iso2_to_iso3` / `faire_wc_country_iso3_to_iso2`

Filter the country code mapping arrays used to convert between ISO 3166-1 alpha-2 and alpha-3 formats. These filters let you add, remove, or override country code mappings.

#### `faire_wc_country_iso2_to_iso3`

| Parameter | Type | Description |
|-----------|------|-------------|
| `$country_codes` | `array` | Associative array mapping alpha-2 to alpha-3 country codes. |

**Since:** 1.0.0
**Source:** [`src/class-country.php:36`](src/class-country.php#L36)

#### `faire_wc_country_iso3_to_iso2`

| Parameter | Type | Description |
|-----------|------|-------------|
| `$country_codes` | `array` | Associative array mapping alpha-3 to alpha-2 country codes. |

**Since:** 1.0.0
**Source:** [`src/class-country.php:315`](src/class-country.php#L315)

<details>
<summary>Example</summary>

```php
add_filter( 'faire_wc_country_iso2_to_iso3', function ( array $codes ): array {
    // Add a custom territory mapping.
    $codes['XK'] = 'XKX'; // Kosovo.
    return $codes;
} );

add_filter( 'faire_wc_country_iso3_to_iso2', function ( array $codes ): array {
    $codes['XKX'] = 'XK'; // Kosovo.
    return $codes;
} );
```
</details>