Keywords: pack quantity, volumeInMl, volume per unit, total volume, pack pricing, product sync, Shopify integration, API product updates

Summary

Pack products in Token of Trust HQ are specified using full pack-scaled amounts, not per-unit values. This applies to both volume (volumeInMl) and pricing fields (wholesalePrice, wholesaleCost, msrp, retailPrice).

The Rule

Why This Matters

When you see a product in HQ with:

• volumeInMl: 60
• packQuantity: 10

This means the total pack volume is 60ml (10 units × 6ml each). The system stores the aggregate value, not the per-unit value.

Integration Behavior

All Integrations Send Full Pack Amounts

Product sync from all integrations (Shopify, BigCommerce, WooCommerce, CSV uploads, API) should specify the full pack-scaled amounts:

• Shopify Product Sync: The volume_in_ml metaobject field should contain the total pack volume
• API /product endpoint: Send total pack volume in the volumeInMl field
• CSV Product Uploads: Specify total pack volume in the Volume column

No Automatic Division or Multiplication

The system does not automatically:

• Divide values by packQuantity when storing products
• Multiply values by packQuantity when displaying products

Values are stored and displayed exactly as received.

When Per-Unit Calculation Happens

Per-unit calculations only occur during tax calculations (in ExciseTaxService.node.js), not during product storage or display. During tax calculation for pack products:

1. Prices are divided by packQuantity to get per-unit pricing for tax assessment
2. Quantities are multiplied by packQuantity to get total unit count

This is internal calculation logic and does not affect how products are stored or displayed in HQ.

Common Mistakes

Incorrect: Specifying Per-Unit Volume

{
  "sku": "10-PACK-6ML",
  "volumeInMl": 6,
  "packQuantity": 10
}

This incorrectly suggests the total pack volume is only 6ml.

Correct: Specifying Full Pack Volume

{
  "sku": "10-PACK-6ML",
  "volumeInMl": 60,
  "packQuantity": 10
}

This correctly indicates 60ml total (10 units × 6ml each).

Troubleshooting

"Why does HQ show a smaller volume than expected for my pack?"

If HQ displays what appears to be per-unit volume for a pack product, check:

1. The source data: Verify what value was sent to the /product API or configured in your integration
2. Shopify metaobject: Check the volume_in_ml field in the Shopify metaobject - it should contain the total pack volume
3. CSV upload: Verify the Volume column contains total pack volume, not per-unit

The issue is at the data entry point, not in HQ's display logic.

Related Code References

• Product API endpoint: modules/product/api/product-api-routes.node.js
• Product storage: services/ExciseTaxService/ExciseTaxProductService.js
• HQ display: website/hq/pages/exciseTax/Products.vue
• Shopify webhook handler: shopify-app/server/productWebhookRoutes.js
• Tax calculation (where per-unit math occurs): services/ExciseTaxService/ExciseTaxService.node.js:562-612

Last updated: December 2025
Investigation reference: Pack volume and pricing specification analysis