Understanding unit value

When you set spend caps, the system needs a per-unit price to deduct from those caps as orders allocate. That number is the variant's unit value, and you'll see it on the Budget Tracking section of every product detail page.

#What unit value is

A single dollar number per variant, used only for spend-controls math. It does not appear on invoices or recipient-facing pages — it's purely the per-unit value used to decrement caps.

Example: a t-shirt variant with unitValue = $14.50. An order with 3 of that variant deducts $43.50 (plus shipping + fees) from your campaign / team / user / account caps.

#How the default is calculated

For a variant that's never been sold via a sales order yet:

• Look at variant.pricing.tiers[]
• Filter to tiers where showToClient = true
• Average their total values

Example: a variant has tiers showing $15.00 at qty 25, $13.50 at qty 100, $12.00 at qty 500. Default unitValue = $13.50 (the average).

If the variant has no showToClient tiers, the default falls back to the average of all positive tiers.

#When it auto-updates

The system listens for sales-order status transitions. When a ClientOrder hits any of:

• CLIENT_APPROVED
• PRODUCTION_DESIGN
• IN_PRODUCTION
• READY_TO_BE_INVOICED
• SHIPPED
• INVOICED
• CLOSED

…it walks the order's line items and updates each variant's unitValue to the negotiated unitPrice on that line.

This means: once you've placed a real sales order at $11/unit, future spend-controls math uses $11 — not the catalog default. The number stays grounded in actual transaction history.

#Manually setting it + the lock toggle

Sometimes you want to override the auto-update. From a product's Budget Tracking section (Admin only):

• Edit the unitValue directly
• Saving auto-locks the variant (so future sales-order transitions don't overwrite your value)

Use the lock toggle to unlock when you want auto-updates to resume.

#How it connects to your caps

Order math (simplified):

projectedTotal = sum(variant.unitValueAtOrder × quantity)
                + shipping
                + fulfillment fees
                + tax / international handling

unitValueAtOrder is a snapshot taken when the order is created — even if you later change the variant's unitValue, the order's accounting stays consistent. The snapshot is what counts against your caps.

#FAQs

What if I never set a unitValue manually? The default works fine. You only need to override when your sales-order pricing differs meaningfully from the catalog tiers (e.g., a custom-priced product).

Will the auto-update affect orders that are already in-flight? No. Each order snapshots the variant's unitValue at order creation. Subsequent updates to the catalog value don't reach already-created orders.

Does this affect what recipients see? Never. Unit value is internal-only. Recipients see no prices.

Why is mine showing "Default avg" instead of the price I expect? The variant likely has no showToClient tiers. Either flag the right tier to show, or set the value manually.