docs: Improvements of PPE docs

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

@@ -18,10 +18,10 @@ Apify Store allows you to monetize your web scraping, automation and AI Agent pr
 
 Actors in Apify Store can be published under one of the following pricing models:
 
-1. **Free**: Users can run the Actor without any additional charges beyond the platform usage costs generated by the Actor.
-2. **Rental**: Users pay for the platform usage costs. However, after a trial period, they need to pay a flat monthly fee to the developer to continue using the Actor.
-3. **Pay per result (PPR)**: Users don't pay for the platform usage costs. Instead, they pay the developer based on the number of results produced by the Actor.
-4. **Pay per event (PPE)**: Users don't pay for the platform usage cost the Actor generates. Instead, they pay based on specific events that are programmatically triggered from the Actor's source code. These events are defined by the developer and can include actions such as generating a single result or starting an Actor.
+1. _Free_: Users can run the Actor without any additional charges beyond the platform usage costs generated by the Actor.
+2. _Rental_: Users pay for the platform usage costs. However, after a trial period, they need to pay a flat monthly fee to the developer to continue using the Actor.
+3. _Pay per result (PPR)_: Users don't pay for the platform usage costs. Instead, they pay the developer based on the number of results produced by the Actor.
+4. _Pay per event (PPE)_: Users don't pay for the platform usage cost the Actor generates. Instead, they pay based on specific events that are programmatically triggered from the Actor's source code. These events are defined by the developer and can include actions such as generating a single result or starting an Actor.
 
 For a detailed comparison of pricing models from the perspective of your users, refer to [Actors in Store](/platform/actors/running/actors-in-store) page.
 
@@ -30,16 +30,15 @@ For a detailed comparison of pricing models from the perspective of your users,
 The following table compares the two main pricing models available for monetizing your Actors:
 
 | Feature/Category         | Rental pricing                | Pay-per-result (PPR)         | Pay-per-event (PPE)           |
-|-------------------------|-------------------------------|------------------------------|-------------------------------|
-| Revenue scalability     | Capped at monthly fee         | Unlimited, scales with usage | Unlimited, scales with usage  |
-| AI/MCP compatibility    | ❌ Not compatible              | ✅ Fully compatible           | ✅ Fully compatible            |
-| User cost predictability| Confusing (rental + usage)    | Clear, transparent pricing   | Clear, transparent pricing    |
-| Tiered pricing support  | ❌ Single price only           | ✅ Store discounts available  | ✅ Store discounts available   |
-| Marketing boost*        | Standard visibility           | Priority store placement     | Priority store placement      |
-| Commission opportunities| Standard 20%                  | Promotional 0% periods       | Promotional 0% periods        |
-| Custom event billing    | Not available                 | Not available                | ✅ Charge for any event        |
+|-------------------------|-------------------------------|-------------------------------|-------------------------------|
+| Revenue scalability     | Capped at monthly fee         | Unlimited, scales with usage  | Unlimited, scales with usage  |
+| AI/MCP compatibility    | ❌ Not compatible             | ✅ Fully compatible           | ✅ Fully compatible           |
+| User cost predictability| Confusing (rental + usage)    | Clear, transparent pricing    | Clear, transparent pricing    |
+| Store discounts         | ❌ Single price only          | ✅ Store discounts available  | ✅ Store discounts available  |
+| Marketing boost*        | Standard visibility           | Priority store placement      | 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)          |
-| Flat monthly fee        | ✅ Yes                         | Not available                | Not available                 |
 
 ## Setting up monetization
 
@@ -108,7 +107,7 @@ All metrics can be exported as JSON for custom analysis and reporting.
 
 ## Promoting your Actor
 
-Create serach-engine-optimized descriptions and README files to improve search engine visibility. Share your Actor on multiple channels:
+Create search-engine-optimized descriptions and README files to improve search engine visibility. Share your Actor on multiple channels:
 
 - Post on Reddit, Quora, and social media platforms
 - Create tutorial videos demonstrating key features

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

@@ -1,5 +1,5 @@
 ---
-title: Pay per event (PPE)
+title: Pay per event
 description: Learn how to monetize your Actor with pay-per-event (PPE) pricing, charging users for specific actions like Actor starts, dataset items, or API calls, and understand how to set profitable, transparent event-based pricing.
 slug: /actors/publishing/monetize/pay-per-event
 sidebar_position: 3
@@ -12,11 +12,11 @@ sidebar_position: 3
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-The pay-per-event pricing model offers a flexible monetization option for Actors on Apify Store. Unlike pay per result, PPE allows you to charge users based on specific events triggered programmatically by your Actor's code.
+The PPE pricing model offers a flexible monetization option for Actors on Apify Store. Unlike pay per result, PPE allows you to charge users based on specific events triggered programmatically by your Actor's code.
 
-PPE lets you define pricing for individual events. You can charge for specific events directly from your Actor by calling the [PPE charging API](/api/v2/post-charge-run), or through [JS](/sdk/js/reference/class/Actor#charge)/[Python](/sdk/python/reference/class/Actor#charge) SDK Common events include Actor start, dataset item creation, and external API calls.
+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 pay-per-event pricing model](#example-of-a-pay-per-event-pricing-model).
+The details on how your cost is computed can be found in [Example of a PPE pricing model](#example-of-a-ppe-pricing-model).
 
 ## How is profit computed
 
@@ -40,7 +40,7 @@ An Actor's negative net profit does not affect the positive profit of another Ac
 
 :::
 
-## How to set pricing for pay-per-event Actors
+## How to set pricing for PPE Actors
 
 1. _Understand your costs_: Analyze resource usage (e.g CPU, memory, proxies, external APIs) and identify cost drivers
 1. _Define clear events_: break your Actor's functionality into measurable, chargeable events.
@@ -51,7 +51,7 @@ An Actor's negative net profit does not affect the positive profit of another Ac
 1. _Test your pricing_: Run your Actor and analyze cost-effectiveness using a special dataset.
 1. _Communicate value_: Ensure pricing reflects the value provided and is competitive.
 
-## Best practices for pay-per-event Actors
+## Best practices for PPE Actors
 
 Use our SDKs (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. This tool can handle pricing, usage tracking, idempotency keys, API errors, and, event charging via an API.
 
@@ -77,9 +77,9 @@ When using browser automation tools like Puppeteer or Playwright for web scrapin
 
 :::
 
-### Charge for "Actor start"
+### Charge for `Actor start`
 
-Charge for "Actor start" to prevent users from running your Actor for free.
+Charge for `Actor start` to prevent users from running your Actor for free.
 
 <Tabs groupId="main">
 <TabItem value="JavaScript" label="JavaScript">
@@ -114,7 +114,7 @@ await Actor.exit();
 </TabItem>
 <TabItem value="Python" label="Python">
 
-```python
+```py
 from apify import Actor
 
 async def charge_for_actor_start():
@@ -139,7 +139,7 @@ async def main():
 
 :::note Actor migrations and charging
 
-Actors can migrate between servers during execution, which restarts the process and clears memory. When using PPE charging, avoid charging the start event multiple times after a migration by checking your charging state.
+Actors can migrate between servers during execution, which restarts the process and clears memory. When using PPE pricing model, avoid charging the start event multiple times after a migration by checking your charging state.
 
 :::
 
@@ -196,7 +196,7 @@ await Actor.exit();
 </TabItem>
 <TabItem value="Python" label="Python">
 
-```python
+```py
 from apify import Actor
 import requests
 
@@ -237,7 +237,7 @@ async def main():
 
 ### Respect user spending limits
 
-Finish the Actor run once charging reaches user-configured Maximum cost per run. Apify SDKs (JS and Python) return ChargeResult that helps determine when to finish.
+Finish the Actor run once charging reaches user-configured Maximum cost per run. Apify SDKs (JS and Python) return `ChargeResult` that helps determine when to finish.
 
 The `eventChargeLimitReached` property checks if the current event type can be charged more. If you have multiple event types, analyze the `chargeableWithinLimit` property to see if other events can still be charged before stopping the Actor.
 
@@ -277,7 +277,7 @@ await Actor.exit();
 </TabItem>
 <TabItem value="Python" label="Python">
 
-```python
+```py
 from apify import Actor
 
 async def charge_for_api_product_detail():
@@ -315,54 +315,50 @@ Try to limit the number of events. Fewer events make it easier for users to unde
 
 ### Make events produce visible results
 
-Try to make your event have tangible artifacts that users can see and understand (this might not be possible when using external APIs). Each charged event should produce something concrete in the user's dataset.
+For Actors that produce data, events should map to something concrete in the user's dataset or storage.
 
-Good examples:
+However, we acknowledge that some events don't produce tangible results (such as running AI workflows or processing external API calls). This flexibility is what makes PPE pricing powerful. It gives you the freedom to charge for special operations, complex workflows, and unique value propositions.
 
-- _"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
+Examples:
 
-Avoid charging for:
-
-- Internal processing steps that don't produce visible results
-- API calls that don't generate user-visible data
-- Setup or configuration steps
-
-This helps users understand exactly what they're paying for and builds trust in your pricing model.
+- _`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
+- _`ai-analysis` event_: Each charge processes one document through an AI workflow (no tangible output, but valuable processing)
 
 ### Use idempotency keys to prevent double charges
 
 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 pay-per-event pricing model
+## Example of a PPE pricing model
 
-You make your Actor pay-per-event and set the following pricing:
+You make your Actor PPE and set 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
+- _`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
-  - Charges: 5 × $0.10 + 1,000 × $0.01 + 50 × $0.05 = $0.50 + $10.00 + $2.50 = $13.00
-- _User 2 (paid plan)_: Starts Actor 2 times, scrapes 500 products, makes 20 product details  
-  - Charges: 2 × $0.10 + 500 × $0.01 + 20 × $0.05 = $0.20 + $5.00 + $1.00 = $6.20
-- _User 3 (free plan)_: Starts Actor 1 time, scrapes 100 products, makes 5 product details
-  - Charges: 1 × $0.10 + 100 × $0.01 + 5 × $0.05 = $0.10 + $1.00 + $0.25 = $1.35
+- _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 $2.50, for the second $1.20, and for the third $0.30.
+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_: $13.00 + $6.20 = $19.20
-- _Total underlying cost_: $2.50 + $1.20 = $3.70
-- _Your profit_: 80% of revenue minus costs = 0.8 × $19.20 - $3.70 = $11.66
+- _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
 
-## PPE event names
+## Event names
 
-To implement pay-per-event 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.
+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.
 
 ## Next steps