feat: Allow adding custom product total amount

[mmustafa-tse]

Background

• A customer requested that add the ability to manually assign a custom product total amount which is by default calculated by multiplying the price by the quantity

What Has Changed

• Added the totalAmount as an optional param when creating a product

Screenshots/Video

• {Include any screenshots or video demonstrating the new feature or fix, if applicable}

Checklist

• I have performed a self-review of my own code.
• I have made corresponding changes to the documentation.
• I have added tests that prove my fix is effective or that my feature works.
• I have tested this locally.

Additional Notes

• {Any additional information or context relevant to this PR}

Reference Issue (For employees only. Ignore if you are an outside contributor)

• Closes https://go/j/SDKE-1173

[cursor]

PR Summary

Medium Risk
Medium risk because it changes the createProduct argument contract and affects how TotalAmount is computed/emitted, which could alter downstream commerce analytics if callers rely on the previous parameter ordering.

Overview
Adds support for custom per-product totals. eCommerce.createProduct now accepts an optional totalAmount parameter and uses it (parsed to a number) instead of always computing Quantity * Price.

Backwards compatibility and coverage. If totalAmount is omitted/invalid it falls back to Quantity * Price, and if an object is passed in that slot it is treated as legacy attributes; tests were added to assert both the default calculation and custom total behavior.

^{Written by Cursor Bugbot for commit 098b107. This will update automatically on new commits. Configure here.}

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

[cursor]

Null totalAmount destroys attributes due to typeof quirk

Medium Severity

The backward-compatibility check typeof totalAmount == 'object' at line 301 also matches null, since typeof null === 'object' in JavaScript. If a caller explicitly passes null for totalAmount (a common pattern when skipping optional positional parameters), sanitizeAttributes(null, name) returns null, overwriting any valid attributes that were already sanitized at line 263. This silently destroys the user's custom attributes.

 

[rmi22186]

Closing per our conversation in DM. This can already be accomplished:

TotalAmount is already computed as Price * Quantity inside createProduct. Instead of adding a new parameter to an already bloated signature, just let the customer override it after creation:
                                                                                                                                               
  const product = mParticle.eCommerce.createProduct('Big Mac', 'sku', 10, 2);
  product.TotalAmount = 15.99; // override with their own calculation                                                                          
  mParticle.eCommerce.logProductAction(ProductActionType.Purchase, product);                                                                   
  This requires zero API changes — no new parameters, no wrapper updates, no interface changes, no breaking changes. TotalAmount is already a  
  property on the product object, and the downstream event logging just reads whatever value is there.             

However, this will need to be added to iOS and Android.