Multi-currency support for CAPI events

[fredrikat]

Description

This PR adds multi-currency support to Facebook Pixel event tracking, ensuring that Purchase and Subscribe events are sent to Meta with the actual
transaction currency instead of the store's default currency. This is critical for WooCommerce stores using multi-currency plugins (e.g., WOOCS, WPML,
Aelia Currency Switcher) to ensure accurate conversion tracking and reporting in Facebook Ads Manager.

Changes made:

• Modified Purchase event tracking to use $order->get_currency() instead of get_woocommerce_currency()
• Updated Subscribe event tracking to use $subscription->get_currency() when available
• Added facebook_for_woocommerce_event_currency filter hook for per-event currency overrides
• Added facebook_for_woocommerce_before_send_api_event filter hook for complete Event object customization
• Added value normalization to (float) for robustness

Context:
Previously, all events were sent with the store's base currency regardless of the actual currency used in the transaction. This caused:

• Incorrect conversion values in Facebook Ads Manager
• Poor ROAS calculations for multi-currency stores
• Difficulty tracking international sales accurately

Type of change

• Fix (non-breaking change which fixes an issue)
• Add (non-breaking change which adds functionality)

Checklist

• I have commented my code, particularly in hard-to-understand areas, if any.
• I have confirmed that my changes do not introduce any new PHPCS warnings or errors.
• I have checked plugin debug logs that my changes do not introduce any new PHP warnings or FATAL errors.
• I followed general Pull Request best practices. Meta employees to follow this wiki.
• I have added tests (if necessary) and all the new and existing unit tests pass locally with my changes.
• I have completed dogfooding and QA testing, or I have conducted thorough due diligence to ensure that it does not break existing functionality.
• I have updated or requested update to plugin documentations (if necessary). Meta employees to follow this wiki.

Changelog entry

Add multi-currency support for Purchase and Subscribe events, ensuring accurate currency tracking for stores using multi-currency plugins

Test Plan

Prerequisites

• WooCommerce store with multi-currency plugin installed (WOOCS, WPML, or Aelia Currency Switcher)
• Facebook for WooCommerce plugin configured with Pixel ID
• Test products available for purchase

Test Steps

Test 1: Purchase Event with Non-Default Currency

1. Switch store currency to a non-default currency (e.g., EUR if base is USD)
2. Add product to cart and complete checkout
3. Verify in Facebook Events Manager that the Purchase event shows:
   - Correct currency (EUR, not USD)
   - Correct value in the transaction currency

Test 2: Subscribe Event with Multi-Currency

1. Install WooCommerce Subscriptions
2. Switch to non-default currency
3. Purchase a subscription product
4. Verify Subscribe event in Events Manager shows correct currency

Test 3: Filter Hook Customization

1. Add the following code to functions.php:
   add_filter('facebook_for_woocommerce_event_currency', function($currency, $event_name, $order) {
   error_log("Event: $event_name, Currency: $currency");
   return $currency;
   }, 10, 3);
2. Complete a purchase
3. Check logs to confirm filter is called with correct parameters

Test 4: Backward Compatibility

1. Test with default currency (no multi-currency plugin)
2. Verify events still track correctly with store base currency
3. Ensure no PHP errors or warnings in debug.log

Expected Results

• Purchase events use $order->get_currency() value
• Subscribe events use subscription currency when available
• Filter hooks allow customization without breaking changes
• No impact on stores without multi-currency plugins
• All existing event tracking continues to work

[meta-cla]

Hi @fredrikat!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at [email protected]. Thanks!

[meta-cla]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!