docs: Improve PPE examples, and add PPR vs PPE section

Author: patrikbraborec

sources/platform/actors/publishing/monetize/pay_per_event.mdx

@@ -191,6 +191,14 @@ If you want to use the synthetic start event, remove the existing start event fr
 
 Charge for things like URLs that appear valid but lead to errors (like 404s) since you had to open the page to discover the error. Return error items with proper error codes and messages instead of failing the entire Actor run.
 
+:::info One call vs two calls
+
+The following code snippets show the single call option to both return error item and charge for the work done.
+
+If you prefer to return error item and charge for the work done in two calls, you can use the two calls option where you charge for the work done with `Actor.charge( ... )` and return the error item with `Actor.pushData( ... )`.
+
+:::
+
 <Tabs groupId="main">
 <TabItem value="JavaScript" label="JavaScript">
 
@@ -294,35 +302,158 @@ You can display a status message or push a record to the dataset to inform users
 
 If you're not using the Apify SDKs (JS/Python), you need to handle idempotency (ensuring the same operation produces the same result when called multiple times) manually to prevent charging the same event multiple times.
 
-## Example of a PPE pricing model
-
-You make your Actor PPE and set the following pricing:
+## Examples of a PPE pricing model
+
+### Example: simple PPE pricing
+
+- `scraped-product`: $0.01 per product - count every product record you return.
+- `scraped-product-detail`: $0.05 per detail - count every enriched product detail you provide.
+
+#### Pricing breakdown by user
+
+<table>
+  <thead>
+    <tr>
+      <th>User</th>
+      <th style={{whiteSpace: 'nowrap'}}>Plan</th>
+      <th style={{width: '40%'}}>Events</th>
+      <th style={{width: '35%'}}>Charges</th>
+      <th style={{whiteSpace: 'nowrap'}}>Total</th>
+      <th style={{whiteSpace: 'nowrap'}}>Cost</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>1</td>
+      <td style={{whiteSpace: 'nowrap'}}>Paid plan</td>
+      <td>
+        <div style={{marginBottom: '4px'}}>1,000 × <code>scraped-product</code></div>
+        <div>50 × <code>scraped-product-detail</code></div>
+      </td>
+      <td>
+        <div style={{marginBottom: '4px'}}>1,000 × $0.01 = $10.00</div>
+        <div>50 × $0.05 = $2.50</div>
+      </td>
+      <td><strong>$12.50</strong></td>
+      <td>$3.20</td>
+    </tr>
+    <tr>
+      <td>2</td>
+      <td style={{whiteSpace: 'nowrap'}}>Paid plan</td>
+      <td>
+        <div style={{marginBottom: '4px'}}>500 × <code>scraped-product</code></div>
+        <div>20 × <code>scraped-product-detail</code></div>
+      </td>
+      <td>
+        <div style={{marginBottom: '4px'}}>500 × $0.01 = $5.00</div>
+        <div>20 × $0.05 = $1.00</div>
+      </td>
+      <td><strong>$6.00</strong></td>
+      <td>$1.50</td>
+    </tr>
+    <tr>
+      <td>3</td>
+      <td style={{whiteSpace: 'nowrap'}}>Free plan</td>
+      <td>
+        <div>5 × <code>scraped-product-detail</code></div>
+      </td>
+      <td>
+        <div style={{marginBottom: '4px'}}>100 × $0.01 = $1.00</div>
+        <div>5 × $0.05 = $0.25</div>
+      </td>
+      <td><strong>$1.25</strong></td>
+      <td>$0.40</td>
+    </tr>
+  </tbody>
+</table>
+
+The platform usage costs are just examples, but you can see the actual costs in the [Computing your costs for PPE and PPR Actors](/platform/actors/publishing/monetize/pricing-and-costs#computing-your-costs-for-ppe-and-ppr-actors) section.
+
+#### Revenue breakdown
+
+- **Revenue (paid users only)**: $12.50 + $6.00 = **$18.50**
+- **Underlying cost (paid users only)**: $3.20 + $1.50 = **$4.70**
+- **Profit**: 0.8 × $18.50 − $4.70 = **$10.10**
+
+### Example: usage-indexed PPE pricing
+
+ - `llm-token-cent`: $0.02 per $0.01 LLM spend - emit one event for each cent billed by your LLM provider.
+
+:::info Simplified example
+
+For the simplicity of the example, we show only the LLM-token-cent event. In reality, you can charge for any event you want.
 
-- _`actor-start` event_: $0.10 per start
-- _`scraped-product` event_: $0.01 per product
-- _`scraped-product-detail` event_: $0.05 per detail
-- _`ai-analysis` event_: $0.15 per analysis
-
-During the first month, three users use your Actor:
-
-- _User 1 (paid plan)_: Starts Actor 5 times, scrapes 1,000 products, makes 50 product details, runs 30 AI analyses
-  - Charges: 5 × $0.10 + 1,000 × $0.01 + 50 × $0.05 + 30 × $0.15 = $0.50 + $10.00 + $2.50 + $4.50 = $17.50
-- _User 2 (paid plan)_: Starts Actor 2 times, scrapes 500 products, makes 20 product details, runs 10 AI analyses
-  - Charges: 2 × $0.10 + 500 × $0.01 + 20 × $0.05 + 10 × $0.15 = $0.20 + $5.00 + $1.00 + $1.50 = $7.70
-- _User 3 (free plan)_: Starts Actor 1 time, scrapes 100 products, makes 5 product details, runs 3 AI analyses
-  - Charges: 1 × $0.10 + 100 × $0.01 + 5 × $0.05 + 3 × $0.15 = $0.10 + $1.00 + $0.25 + $0.45 = $1.80
-
-Let's say the underlying platform usage for the first user is $3.20, for the second $1.50, and for the third $0.40.
-
-Your profit is computed only from the first two users, since they are on Apify paid plans. The revenue breakdown is:
+:::
 
-- _Total revenue_: $17.50 + $7.70 = $25.20
-- _Total underlying cost_: $3.20 + $1.50 = $4.70
-- _Your profit_: 80% of revenue minus costs = 0.8 × $25.20 - $4.70 = $15.46
+#### Pricing breakdown by user
+
+<table>
+  <thead>
+    <tr>
+      <th>User</th>
+      <th style={{whiteSpace: 'nowrap'}}>Plan</th>
+      <th style={{width: '45%'}}>Events</th>
+      <th style={{width: '35%'}}>Charges</th>
+      <th style={{whiteSpace: 'nowrap'}}>Total</th>
+      <th style={{whiteSpace: 'nowrap'}}>Cost</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>1</td>
+      <td style={{whiteSpace: 'nowrap'}}>Paid plan</td>
+      <td>
+        <div style={{marginBottom: '4px'}}>$25.40 LLM usage:</div> 
+        <div>2,540 × <code>llm-token-cent</code></div>
+      </td>
+      <td>
+        <div>2,540 × $0.02 = $50.80</div>
+      </td>
+      <td><strong>$50.80</strong></td>
+      <td>$2.60</td>
+    </tr>
+    <tr>
+      <td>2</td>
+      <td style={{whiteSpace: 'nowrap'}}>Paid plan</td>
+      <td>
+        <div style={{marginBottom: '4px'}}>$12.10 LLM usage:</div>
+        <div>1,210 × <code>llm-token-cent</code></div>
+      </td>
+      <td>
+        <div>1,210 × $0.02 = $24.20</div>
+      </td>
+      <td><strong>$24.20</strong></td>
+      <td>$1.20</td>
+    </tr>
+    <tr>
+      <td>3</td>
+      <td style={{whiteSpace: 'nowrap'}}>Free plan</td>
+      <td>
+        <div style={{marginBottom: '4px'}}>$3.90 LLM usage:</div>
+        <div>390 × <code>llm-token-cent</code></div>
+      </td>
+      <td>
+        <div>390 × $0.02 = $7.80</div>
+      </td>
+      <td><strong>$7.80</strong></td>
+      <td>$0.35</td>
+    </tr>
+  </tbody>
+</table>
+
+The platform usage costs are just examples, but you can see the actual costs in the [Computing your costs for PPE and PPR Actors](/platform/actors/publishing/monetize/pricing-and-costs#computing-your-costs-for-ppe-and-ppr-actors) section.
+
+#### Revenue breakdown
+
+- **Revenue (paid users only)**: $50.80 + $24.20 = **$75.00**
+- **Underlying cost (paid users only)**: $2.60 + $1.20 = **$3.80**
+- **Profit**: 0.8 × $75.00 − $3.80 = **$56.20**
+
+This example illustrates the key trade-off of PPE pricing: while it's harder for users to predict exact costs upfront, it provides developers with a safer and more scalable revenue model that grows with actual usage.
 
 ## Event names
 
-To implement PPE pricing, you need to define specific events in your Actor code. You can retrieve the list of available pricing event names using the [Get Actor](https://apify.com/docs/api/v2/act-get) API endpoint.
+If you need to know your event names, you can retrieve the list of available pricing event names using the [Get Actor](https://apify.com/docs/api/v2/act-get) API endpoint.
 
 ## Next steps
 

sources/platform/actors/publishing/monetize/pay_per_result.mdx

@@ -35,6 +35,16 @@ where:
 
 Only revenue and cost for Apify customers on paid plans are taken into consideration when computing your profit. Users on free plans are not reflected there.
 
+## PPR vs PPE
+
+PPR charges based on the number of results produced. PPE lets you define pricing for individual events, and help you to make your pricing more flexible. You can charge for specific events directly from your Actor by calling the PPE charging API. 
+
+:::info Learn more about PPE
+
+If you want to learn more about PPE, please refer to the [Pay per event](/platform/actors/publishing/monetize/pay-per-event) section.
+
+:::
+
 ## Best practices for PPR Actors
 
 To ensure profitability, check the following best practices.
@@ -201,19 +211,68 @@ This ensures that every run generates at least one result, guaranteeing that use
 
 ## Example of PPR pricing model
 
-You make your Actor PPR and set the price to be _$1/1,000 results_. During the first month, three users use your Actor:
-
-- _User 1 (paid plan)_: Gets 50,000 results, costing them $50
-- _User 2 (paid plan)_: Gets 20,000 results, costing them $20
-- _User 3 (free plan)_: Gets 5,000 results, costing them $0
-
-Let's say the underlying platform usage for the first user is $5, for the second $2, and for the third $0.5.
-
-Your profit is computed only from the first two users, since they are on Apify paid plans. The revenue breakdown is:
-
-- _Total revenue_: $50 + $20 = $70
-- _Total underlying cost_: $5 + $2 = $7
-- _Your profit_: 80% of revenue minus costs = 0.8 × $70 - $7 = $49
+You make your Actor PPR and set the price to be _$1/1,000 results_. During the first month, three users use your Actor.
+
+#### Pricing breakdown by user
+
+<table>
+  <thead>
+    <tr>
+      <th>User</th>
+      <th style={{whiteSpace: 'nowrap'}}>Plan</th>
+      <th style={{width: '35%'}}>Results</th>
+      <th style={{width: '45%'}}>Charges</th>
+      <th style={{whiteSpace: 'nowrap'}}>Total</th>
+      <th style={{whiteSpace: 'nowrap'}}>Cost</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>1</td>
+      <td style={{whiteSpace: 'nowrap'}}>Paid plan</td>
+      <td>
+        <div>50,000 results</div>
+      </td>
+      <td>
+        <div>50,000 ÷ 1,000 × $1.00 = $50.00</div>
+      </td>
+      <td><strong>$50.00</strong></td>
+      <td>$5.00</td>
+    </tr>
+    <tr>
+      <td>2</td>
+      <td style={{whiteSpace: 'nowrap'}}>Paid plan</td>
+      <td>
+        <div>20,000 results</div>
+      </td>
+      <td>
+        <div>20,000 ÷ 1,000 × $1.00 = $20.00</div>
+      </td>
+      <td><strong>$20.00</strong></td>
+      <td>$2.00</td>
+    </tr>
+    <tr>
+      <td>3</td>
+      <td style={{whiteSpace: 'nowrap'}}>Free plan</td>
+      <td>
+        <div>5,000 results</div>
+      </td>
+      <td>
+        <div>5,000 ÷ 1,000 × $1.00 = $5.00</div>
+      </td>
+      <td><strong>$0.00</strong></td>
+      <td>$0.50</td>
+    </tr>
+  </tbody>
+</table>
+
+The platform usage costs are just examples, but you can see the actual costs in the [Computing your costs for PPE and PPR Actors](/platform/actors/publishing/monetize/pricing-and-costs#computing-your-costs-for-ppe-and-ppr-actors) section.
+
+#### Revenue breakdown
+
+- **Revenue (paid users only)**: $50.00 + $20.00 = **$70.00**
+- **Underlying cost (paid users only)**: $5.00 + $2.00 = **$7.00**
+- **Profit**: 0.8 × $70.00 − $7.00 = **$49.00**
 
 ## Next steps