docs: PPE docs improvements (#1948)

Author: patrikbraborec

apify-api/openapi/paths/actor-runs/actor-runs@{runId}@charge.yaml

@@ -7,6 +7,12 @@ post:
     The event you are charging for must be one of the configured events in your Actor. If the Actor is not set up as pay per event, or if the event is not configured,
     the endpoint will return an error. The endpoint must be called from the Actor run itself, with the same API token that the run was started with.
 
+    :::info Learn more about pay-per-event pricing
+
+    For more details about pay-per-event (PPE) pricing, refer to our [PPE documentation](/platform/actors/publishing/monetize/pay-per-event).
+
+    :::
+
   operationId: PostChargeRun
   parameters:
     - name: runId

sources/academy/ai/ai-agents.mdx

@@ -251,6 +251,12 @@ Common issues and solutions:
 
 Apify's pay-per-event (PPE) pricing model allows charging users based on specific triggered events through the API or SDKs.
 
+:::info How pay-per-event pricing works
+
+If you want more details about PPE pricing, refer to our [PPE documentation](/platform/actors/publishing/monetize/pay-per-event).
+
+:::
+
 ### Step 1: Define chargeable events
 
 You can configure charges for events like the Actor starting, a task completing successfully, or custom events such as specific API calls.

sources/academy/platform/get_most_of_actors/store_basics/how_actor_monetization_works.md

@@ -33,7 +33,11 @@ Monetizing your Actor on the Apify platform involves several key steps:
   - 2nd user starts their trial but pays next month.
   - 3rd user on a free plan finishes the trial without upgrading to a paid plan and can’t use the Actor further.
 
-Learn more about the rental pricing model in our [documentation](/platform/actors/publishing/monetize#rental-pricing-model).
+:::info Rental pricing details
+
+If you want more details about rental pricing, refer to our [rental pricing documentation](/platform/actors/publishing/monetize/rental).
+
+:::
 
 ### Pay-per-result pricing model
 
@@ -49,7 +53,11 @@ Learn more about the rental pricing model in our [documentation](/platform/actor
   - Dataset storage: $1 per 1,000 GB-hours
 - _Example_: you set a price of $1 per 1,000 results. Two users generate 50,000 and 20,000 results, paying $50 and $20, respectively. If the platform usage costs are $5 and $2, your profit is $49.
 
-Learn more about the pay-per-result pricing model in our [documentation](/platform/actors/publishing/monetize#pay-per-result-pricing-model).
+:::info Pay-per-result details
+
+If you want more details about PPR pricing, refer to our [PPR documentation](/platform/actors/publishing/monetize/pay-per-result).
+
+:::
 
 ### Pay-per-event pricing model
 
@@ -77,7 +85,11 @@ Learn more about the pay-per-result pricing model in our [documentation](/platfo
     - This comes up to $1.625 of total revenue
   - That means if platform usage costs are $0.365 for user A and $0.162 for user B your profit is $4.748
 
-Learn more about the pay-per-event pricing model in our [documentation](/platform/actors/publishing/monetize#pay-per-event-pricing-model).
+:::info Pay-per-event details
+
+If you want more details about PPE pricing, refer to our [PPE documentation](/platform/actors/publishing/monetize/pay-per-event).
+
+:::
 
 ## Setting up monetization
 

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

@@ -35,7 +35,7 @@ The following table compares the two main pricing models available for monetizin
 | AI/MCP compatibility    | ❌ Not compatible             | ✅ Fully compatible           | ✅ Fully compatible           |
 | User cost predictability| Unpredictable (rental + usage)    | Predictable    | Predictable    |
 | Store discounts         | ❌ Single price only          | ✅ Store discounts available  | ✅ Store discounts available  |
-| Marketing boost         | Standard visibility           | Priority store placement      | Priority store placement      |
+| Marketing boost         | Standard visibility           | Standard visibility           | Priority store placement      |
 | Commission opportunities| Standard 20%                  | Standard 20%                  | Promotional 0% periods        |
 | Custom event billing    | Not available                 | Not available                 | ✅ Charge for any event       |
 | Per-result billing      | Not available                 | ✅ Charge per dataset item    | Optional (via event)          |

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

@@ -16,11 +16,11 @@ The PPE pricing model offers a flexible monetization option for Actors on Apify
 
 PPE lets you define pricing for individual events. You can charge for specific events directly from your Actor using the [JS](/sdk/js/reference/class/Actor#charge)/[Python](/sdk/python/reference/class/Actor#charge) SDK, or by calling the [PPE charging API](/api/v2/post-charge-run) directly. Common events include Actor start, dataset item creation, and external API calls.
 
-The details on how your cost is computed can be found in [Example of a PPE pricing model](#example-of-a-ppe-pricing-model).
+The details on how your cost is computed can be found in [Example of a PPE pricing](#example-of-a-ppe-pricing).
 
 :::tip Additional benefits
 
-Actors that implement PPE pricing receive additional benefits, including increased visibility in Apify Store and enhanced discoverability for users looking for monetized solutions.
+Actors that implement PPE pricing receive additional benefits, including increased visibility in Apify Store and enhanced discoverability.
 
 :::
 
@@ -132,44 +132,36 @@ When using [Crawlee](https://crawlee.dev/), use `crawler.autoscaledPool.abort()`
 
 ## Best practices for PPE Actors
 
-Use our SDKs ([JS](/sdk/js/) and, [Python](/sdk/python/) or use [`apify actor charge`](/cli/docs/next/reference#apify-actor-charge-eventname) when using our Apify CLI) to simplify PPE implementation into your Actor. This tool can handle pricing, usage tracking, idempotency keys, API errors, and, event charging via an API.
+Use our [SDKs](/sdk) (JS and, Python or use [`apify actor charge`](/cli/docs/next/reference#apify-actor-charge-eventname) when using our Apify CLI) to simplify PPE implementation into your Actor. SDKs help you handle pricing, usage tracking, idempotency keys, API errors, and, event charging via an API. You can also choose not to use it, but then you must handle API integration and possible edge cases manually.
 
-You can also choose not to use it, but then you must handle API integration and possible edge cases manually.
-
-### Set memory limits
-
-Set memory limits using `minMemoryMbytes` and `maxMemoryMbytes` in your [`actor.json`](https://docs.apify.com/platform/actors/development/actor-definition/actor-json) file to control platform usage costs.
-
-```json
-{
-    "actorSpecification": 1, 
-    "name": "name-of-my-scraper",
-    "version": "0.0",
-    "minMemoryMbytes": 512,
-    "maxMemoryMbytes": 1024,
-}
-```
+### Use synthetic start event `apify-actor-start`
 
-:::note Memory requirements for browser-based scraping
+:::info Synthetic Actor recommended
 
-When using browser automation tools like Puppeteer or Playwright for web scraping, increase the memory limits to accommodate the browser's memory usage.
+We recommend using the synthetic Actor start event in PPE Actors. It benefits both you and your users.
 
 :::
 
-### Use synthetic start event `apify-actor-start`
-
-This event is automatically charged by the Apify platform when an Actor is started or resurrected.
+Starting an Actor takes time, and creates additional cost for the Actor creator, because the profit equals revenue minus platform costs.
 
-Users of your Actor are charged one event for each GB of memory used by the Actor (at least one event per run). We _strongly_ suggest setting the price of this event to $0.0001 to remain competitive in the Store and attractive for your customers. If you define this event, you also save 5 seconds of Actor runtime from each Actor run, which won't be deducted from your payout profits.
+One of the options to charge for the time spent on starting the Actor is to charge an “Actor start” event. Unfortunately, this makes your Actor comparably expensive with other tools on the market (outside of [Apify Store](/platform/console/store)) that do not incur this startup cost.
 
-:::note Automatic charging of synthetic start event
+We want to make it easier for Actor creators to stay competitive, but also help them to be profitable. Therefore, we have the Apify Actor synthetic start event `apify-actor-start`. This event is enabled by default for all new PPE Actors, and when you use it Apify will cover the compute unit cost of the first 5 seconds of every Actor run.
 
-You must _not_ manually charge for the synthetic start event (`apify-actor-start`) in your Actor code.
+The default price of the event is set intentionally low. This pricing means that the free 5 seconds of compute we provide costs us more than the revenue generated from the event. We've made this investment to _support our creator community_ by reducing your startup costs while keeping your Actors competitively priced for users.
 
-If you attempt to charge this event yourself, the operation will fail.
-This event is _always_ charged automatically by the Apify platform whenever your Actor starts or is resurrected.
+#### How the synthetic start event works
 
-:::
+- The Apify Actor start event is _automatically enabled_ for all new PPE Actors. For existing Actors, you can enable it in Apify Console.
+- Apify _automatically charges_ the event.
+  - You must _not_ manually charge for the synthetic start event (`apify-actor-start`) in your Actor code. If you attempt to charge this event yourself, the operation will fail.
+- The default price of the event is _$0.00005_, which equals _$0.05 per 1,000 starts_. We recommend keeping the default price to keep your Actors competitive.
+- The number of events charged _depends on the memory_ of the Actor run. Up to and including 1 GB of RAM, the event is charged once. Then it's charged once for each extra GB of memory. For example:
+  - 128 MB RAM: 1 event, $0.00005
+  - 1 GB RAM: 1 event, $0.00005
+  - 4 GB RAM: 4 events, $0.0002
+- You can increase the price of the event if you wish, but you _won't get more free compute_.
+- You can delete the event if you wish, but if you do, you will _lose the free 5 seconds_ of compute.
 
 #### Synthetic start event for new Actors
 
@@ -179,18 +171,40 @@ For new Actors, this event is added automatically as you can see on the followin
 
 #### Synthetic start event for existing Actors
 
-If you have existing Actors, you can add this event manually in Apify Console.
+If you have existing Actors, you can add this event manually in Apify Console in the **Publication** tab.
 
 #### Synthetic start event for Actors with start event
 
 Your Actor might already have a start event defined, such as `actor-start` or another variant of the event name. In this case, you can choose whether to use the synthetic start event or keep the existing start event.
 
-If you want to use the synthetic start event, remove the existing start event from your Actor and add the synthetic start event in Apify Console.
+If you want to use the synthetic start event, remove the existing start event from your Actor and add the synthetic start event in Apify Console in the **Publication** tab.
+
+### Set memory limits
+
+Set memory limits using `minMemoryMbytes` and `maxMemoryMbytes` in your [`actor.json`](https://docs.apify.com/platform/actors/development/actor-definition/actor-json) file to control platform usage costs.
+
+```json
+{
+    "actorSpecification": 1, 
+    "name": "name-of-my-scraper",
+    "version": "0.0",
+    "minMemoryMbytes": 512,
+    "maxMemoryMbytes": 1024,
+}
+```
+
+:::note Memory requirements for browser-based scraping
+
+When using browser automation tools like Puppeteer or Playwright for web scraping, increase the memory limits to accommodate the browser's memory usage.
+
+:::
 
 ### Charge for invalid input
 
 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.
 
+The snippet below shows how you can charge for invalid inputs using `Actor.pushData` when a dataset item is created and the `scraped-result` event is charged.
+
 <Tabs groupId="main">
 <TabItem value="JavaScript" label="JavaScript">
 
@@ -279,9 +293,9 @@ However, we acknowledge that some events don't produce tangible results (such as
 
 Examples:
 
-- _`scraped-product` event_: Each charge adds one product record to the dataset
-- _`processed-image` event_: Each charge adds one processed image to the dataset  
-- _`extracted-review` event_: Each charge adds one review to the dataset
+- _`post` event_: Each charge adds one social media post to the dataset
+- _`profile` event_: Each charge adds one user profile to the dataset  
+- _`processed-image` event_: Each charge adds one processed image to the dataset
 - _`ai-analysis` event_: Each charge processes one document through an AI workflow (no tangible output, but valuable processing)
 
 :::note Additional context
@@ -294,35 +308,97 @@ 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
+## Example of a PPE pricing
 
-You make your Actor PPE and set the following pricing:
+You create a social media monitoring Actor with the following pricing:
 
-- _`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
+- `post`: $0.002 per post - count every social media post you extract.
+- `profile`: $0.005 per profile - count every user profile you extract.
+- `sentiment-analysis`: $0.01 per post - count every post analyzed for sentiment, engagement metrics, and content classification using external LLM APIs.
 
-During the first month, three users use your Actor:
+:::info Fixed pricing vs. usage-based pricing
 
-- _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
+You have two main strategies for charging AI-related operations:
 
-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.
+1. _Fixed event pricing_ (like `sentiment-analysis` above): Charge a fixed amount per operation, regardless of actual LLM costs
+2. _Usage-based pricing_: Use events like `llm-token` that charge based on actual LLM usage costs
 
-Your profit is computed only from the first two users, since they are on Apify paid plans. The revenue breakdown is:
+Fixed pricing is simpler for users to predict, while usage-based pricing more accurately reflects your actual costs.
+
+:::
 
-- _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'}}>Platform cost</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>1</td>
+      <td style={{whiteSpace: 'nowrap'}}>Paid plan</td>
+      <td>
+        <div style={{marginBottom: '4px'}}>5,000 × <code>post</code></div>
+        <div>1,000 × <code>sentiment-analysis</code></div>
+      </td>
+      <td>
+        <div style={{marginBottom: '4px'}}>5,000 × $0.002</div>
+        <div>1,000 × $0.01</div>
+      </td>
+      <td><strong>$20</strong></td>
+      <td>$2.50</td>
+    </tr>
+    <tr>
+      <td>2</td>
+      <td style={{whiteSpace: 'nowrap'}}>Paid plan</td>
+      <td>
+        <div style={{marginBottom: '4px'}}>3,000 × <code>post</code></div>
+        <div>500 × <code>sentiment-analysis</code></div>
+      </td>
+      <td>
+        <div style={{marginBottom: '4px'}}>3,000 × $0.002</div>
+        <div>500 × $0.01</div>
+      </td>
+      <td><strong>$11</strong></td>
+      <td>$1.50</td>
+    </tr>
+    <tr>
+      <td>3</td>
+      <td style={{whiteSpace: 'nowrap'}}>Free plan</td>
+      <td>
+        <div style={{marginBottom: '4px'}}>1,000 × <code>post</code></div>
+        <div>100 × <code>sentiment-analysis</code></div>
+      </td>
+      <td>
+        <div style={{marginBottom: '4px'}}>1,000 × $0.002</div>
+        <div>100 × $0.01</div>
+      </td>
+      <td><strong>$3</strong></td>
+      <td>$0.40</td>
+    </tr>
+  </tbody>
+</table>
+
+Your profit and costs are computed _only from the first two users_ since they are on Apify paid plans.
+
+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)_: $20 + $11 = _\$31_
+- _Platform cost (paid users only)_: $2.50 + $1.50 = _\$4_
+- _Profit_: 0.8 × $31 − $4 = _\$20.80_
 
 ## 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