@apex-inc/sdk 0.17.1 → 0.17.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@apex-inc/sdk",
-  "version": "0.17.1",
-  "description": "Event tracking and identity SDK for Apex — currently in private beta.",
+  "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",
   "types": "dist/index.d.ts",

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

@@ -181,10 +181,32 @@ 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. A channel switches to leading with
-LTGP:CAC once at least 60% of its net revenue carries reported cost.
+which is a complete answer on its own.
+
+**Cost is all-or-nothing per order.** Every line item that carries a price or a
+product id must also carry a cost, or Apex treats that order as cost-unknown
+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.
+
+**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