docs: add new section regarding PPE based on alpha PPE docs (#1481)

Author: TC-MO

sources/platform/actors/publishing/images/monetization_wizard.png

@@ -9,6 +9,9 @@ sidebar_position: 2
 
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 Apify Store allows you to monetize your web scraping and automation projects by publishing them as Paid Actors. This guide explains the available pricing models and how to get started.
 
 ## Pricing models
@@ -17,8 +20,8 @@ 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**: 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**: 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.
+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.
 
 ### Rental pricing model
 
@@ -71,22 +74,88 @@ You make your Actor pay-per-result and set the price to be $1/1,000 results. Dur
 Your profit is computed only from the first two users, since they are on Apify paid plans. The revenue for the first user is $50 and for the second $20, i.e., total revenue is $70. The total underlying cost is _$5 + $2 = $7_. Since your profit is 80% of the revenue minus the cost, it would be _0.8 * 70 - 7 = $49_.
 </details>
 
-#### Best practices for Pay-per-results Actors
+#### Best practices for PPR Actors
 
 To ensure profitable operation:
 
 - Set memory limits in your [`actor.json`](https://docs.apify.com/platform/actors/development/actor-definition/actor-json) file to control platform usage costs
 - Implement the `ACTOR_MAX_PAID_DATASET_ITEMS` check to prevent excess result generation
 - Test your Actor with various result volumes to determine optimal pricing
 
+### Pay-per-event pricing model
+
+The pay-per-event pricing model offers a flexible monetization option for Actors on Apify Store. Unlike the pay-per-result, PPE allows you to charge users based on specific events triggered programmatically by your Actor's code.
+
+#### PPE vs PPR
+
+Unlike PPR, which charges based on the number of results produced, PPE lets you define pricing for individual events. You can charge for specific events directly from your Actor by calling the PPE charging API. Common events include Actor start, dataset item creation, and external API calls.
+
+For a detailed comparison of pricing models, refer to our [user-facing documentation](/platform/actors/running/actors-in-store).
+
+#### How is profit computed
+
+Your profit is calculated as follows:
+
+`profit = (0.8 * revenue) - platform costs`
+
+where:
+
+- _Revenue_: The amount charged for events via the PPE [API](/api/v2/post-charge-run) or through [JS](/sdk/js/reference/class/Actor#charge)/[Python](/sdk/python/reference/class/Actor#charge) SDK. You receive 80% of this revenue.
+- _Platform costs_: The underlying platform usage costs for running the Actor, calculated using the same unit pricing as PPR.
+
+Only paid user activity is included in profit calculations.
+
+#### How to set pricing for PPE
+
+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.
+1. _Common use cases_:
+   1. _For scraping_: combine Actor start and dataset items pricing to reflect setup and per-result cost.
+   1. _Beyond scraping_: Account for intergrations with external systems or external API calls.
+1. _External API costs_: Account for additional processing costs.
+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 competetive.
+
+#### Best practices for PPE Actors
+
+- Set memory limits in your [`actor.json`](/platform/actors/development/actor-definition/actor-json) file to control platform usage costs
+- Avoid duplicate charges by not calling the start Actor event during migration.
+- Ensure users are not charged beyond their set maximum. The [`ChargingManager`](https://github.com/metalwarrior665/actor-charge-manager-poc) or our SDKs ([JS](/sdk/js/reference/class/ChargingManager) and [Python](/sdk/python/reference/class/ChargingManager)) can handle this logic.
+- Use idempotency keys in API calls to prevent double charges.
+- Try to limit the number of evernt. Fewer events makes it easier for users to understand your pricing.
+- Try to make your event have tangible artifacts that users can see and understand (this might be not possible when using external APIs) i.e:
+  - Get a record
+  - Save it to dataset
+  - etc.
+
+:::note `ChargingManager` usage
+
+Use our [`ChargingManager`](https://github.com/metalwarrior665/actor-charge-manager-poc) or SDKs ([JS](/sdk/js/reference/class/ChargingManager) and, [Python](/sdk/python/reference/class/ChargingManager) 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.
+
+You can also choose not to use it, but then you must handle API integration and possible edge cases manually. You can use `ChargingManager` code as a reference.
+
+:::
+
 ## Setting up monetization
 
 Navigate to your [Actor page](https://console.apify.com/actors?tab=my) in Apify Console, choose Actor that you want to monetize, and select the Publication tab.
 ![Monetization section](./images/monetization-section.png)
 Open the Monetization section and complete your billing and payment details.
 ![Set up monetization](./images/monetize_actor_set_up_monetization.png)
-Follow the monetization wizard to configure. Follow the monetization wizard to configure your pricing model.
+Choose the pricing model for your Actor.
 ![Monetization wizard](./images/monetization_wizard.png)
+Follow the monetization wizard to configure your pricing model.
+<Tabs>
+<TabItem value="Rental" label="Rental">
+![rental moentization wizard](./images/rental-wizard.png)
+</TabItem>
+<TabItem value="Pay-per-result" label="Pay-per-result">
+![ppr moentization wizard](./images/ppr-wizard.png)
+</TabItem>
+<TabItem value="Pay-per-event" label="Pay-per-event">
+![ppe moentization wizard](./images/ppe-wizard.png)
+</TabItem>
+</Tabs>
 
 ## Changing monetization