diff --git a/apps/docs/mintlify/documentation/modelling-pricing/proration.mdx b/apps/docs/mintlify/documentation/modelling-pricing/proration.mdx
index 7c3c8f93f..8760f1007 100644
--- a/apps/docs/mintlify/documentation/modelling-pricing/proration.mdx
+++ b/apps/docs/mintlify/documentation/modelling-pricing/proration.mdx
@@ -147,6 +147,23 @@ curl -X POST https://api.useautumn.com/v2/billing/attach \
 In these cases, Autumn requires immediate billing and will return an error.
 </Warning>
 
+### Custom line items
+
+If you need full control over what the customer is charged during a plan switch, you can pass `custom_line_items` to replace the auto-generated proration invoice entirely. This is only valid for immediate plan changes (e.g. upgrades).
+
+```typescript
+await autumn.billing.attach({
+  customerId: "user_123",
+  planId: "enterprise",
+  customLineItems: [
+    { amount: 25, description: "Prorated upgrade credit" },
+    { amount: -10, description: "Loyalty discount" },
+  ],
+});
+```
+
+When `custom_line_items` is provided, Autumn skips its own proration calculation and creates an invoice with exactly the line items you specified. Amounts can be negative to represent credits.
+
 ## Usage-based proration
 
 For usage-based prices, when a plan change occurs mid-cycle: