@apex-inc/sdk 0.17.2 → 0.17.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-inc/sdk",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "description": "Event tracking and identity SDK for Apex \u2014 currently in private beta.",
   "main": "dist/index.js",
   "module": "dist/esm/index.js",

package/skills/apex-integration-cookbook/SKILL.md

@@ -181,7 +181,11 @@ data: {
 data: { order_id: "ord_123", value: 99.0, currency: "USD", cost: 48.5 }
 ```
 
-`unit_cost` aliases: `cost`, `cogs`, `cost_of_goods`, `item_cost`. Cost is
+`unit_cost` aliases: `unitCost`, `item_cost`. All three are PER UNIT — Apex
+multiplies by `quantity`. Do not send a line total under any of them, and note
+that `cost` is **not** an alias at the line level: it means an order total, so
+sending a $150 line total as `cost` on a line with `quantity: 3` would be read
+as $450. If you only know the total, use the order-level shape above. Cost is
 never inferred — omit it and every channel is measured and ranked on LTV:CAC,
 which is a complete answer on its own.
 
@@ -191,8 +195,18 @@ and it contributes to LTV:CAC only. This matters most during a rollout: if you
 instrument 70 of 100 SKUs, a mixed order would otherwise report the cost of the
 70% as if it were the whole order, which inflates gross profit rather than
 leaving it blank. Send `cost` at the order level if per-item cost isn't
-available for every line. Each channel's LTGP:CAC states the share of revenue
-behind it, so partial rollouts read as a small sample instead of a wrong number.
+available for every line.
+
+**How partial coverage is handled.** Apex measures your margin on the orders
+where every item reported a cost, then applies that margin rate to all of the
+channel's revenue. Each channel's LTGP:CAC states the share of revenue the
+margin was measured on, so a partial rollout reads as a small sample rather than
+a wrong number — and LTGP:CAC can never come out above LTV:CAC.
+
+**Refunds reverse gross profit.** Send `order_id` on the refund event (or link
+it to the original charge) and Apex reverses that order's margin in proportion
+to the amount refunded. A refund with no way to identify the original order
+still reduces revenue, but leaves the margin untouched.
 
 ## Event naming conventions