diff --git a/sources/platform/actors/development/programming_interface/status_messages.md b/sources/platform/actors/development/programming_interface/status_messages.md index 832b8f918..6d904732e 100644 --- a/sources/platform/actors/development/programming_interface/status_messages.md +++ b/sources/platform/actors/development/programming_interface/status_messages.md @@ -15,7 +15,7 @@ import TabItem from '@theme/TabItem'; Each Actor run has a status, represented by the `status` field. The following table describes the possible values: |Status|Type|Description| -|--- |--- |--- | +|---|---|---| |`READY`|initial|Started but not allocated to any worker yet| |`RUNNING`|transitional|Executing on a worker| |`SUCCEEDED`|terminal|Finished successfully| @@ -76,3 +76,15 @@ async def main(): + +## Communicate limitations + +If your Actor has specific limitations for users on the Apify free plan (e.g., restricted features, limited results), communicate these clearly to avoid confusion. + +- Status messages: Use `Actor.setStatusMessage` or `Actor.exit` message to explain why a run finished early or failed (e.g., "This Actor has a special daily limit for free plan users. This was set by the Actor developer, not Apify. Upgrade to continue."). +- Provide clear error messages: Don't return generic system errors or fail the run in a way that looks like a platform issue. This frustrates users and makes troubleshooting difficult. + - Wrong: API usage is limited to 10 results + - Right: This Actor only allows up to 10 results for free users. Upgrade to a paid plan to receive unlimited results. +- Documentation: Clearly state any limitations in your Actor's `README` and input schema descriptions so users know what to expect before running the Actor. + - General restrictions (like limiting the number of results) must be explained in the top-level input schema description that renders above the input editor UI. + - Feature-specific limitations must be included in the title of an input field. The title must include explanation in parenthesis such as `(paying users only)` or `(limited for free users)`. E.g. `Max comments (paying users only)`. diff --git a/sources/platform/actors/publishing/monetize/index.mdx b/sources/platform/actors/publishing/monetize/index.mdx index 1c0df062c..89ccfa12a 100644 --- a/sources/platform/actors/publishing/monetize/index.mdx +++ b/sources/platform/actors/publishing/monetize/index.mdx @@ -29,18 +29,18 @@ 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 | 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| Unpredictable (rental + usage) | Predictable | Predictable | -| Store discounts | ❌ Single price only | ✅ Store discounts available | ✅ Store discounts available | -| Marketing boost | Standard visibility | Standard visibility | Priority store placement | -| Commission opportunities| Standard 20% | Standard 20% | Standard 20% | -| Custom event billing | Not available | Not available | ✅ Charge for any event | -| Per-result billing | Not available | ✅ Charge per dataset item | Optional (via event; automatic via `apify-default-dataset-item`) | - -## Setting up monetization +| Feature/Category | Rental | 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 | Unpredictable (rental + usage) | Predictable | Predictable | +| Store discounts | ❌ Single price only | ✅ Store discounts available | ✅ Store discounts available | +| Marketing boost | Standard visibility | Standard visibility | Priority store placement | +| Commission opportunities | Standard 20% | Standard 20% | Standard 20% | +| Custom event billing | Not available | Not available | ✅ Charge for any event | +| Per-result billing | Not available | ✅ Charge per dataset item | Optional (via event; automatic via `apify-default-dataset-item`) | + +## Set up monetization Navigate to your [Actor page](https://console.apify.com/actors?tab=my) in Apify Console, choose the Actor that you want to monetize, and select the Publication tab. ![Monetization section](../images/monetization-section.png) @@ -61,7 +61,7 @@ Follow the monetization wizard to configure your pricing model. -### Changing monetization +### Change monetization You can change the monetization setting of your Actor by using the same wizard as for the setup in the **Monetization** section of your Actor's **Publication** tab. @@ -100,6 +100,14 @@ If no action is taken, the payout will be automatically approved on the 14th, wi If the monthly profit does not meet these thresholds, as per our [Terms & Conditions](https://apify.com/store-terms-and-conditions), the funds will roll over to the next month until the threshold is reached. +## Handle free users + +When monetizing your Actor, you might want to limit features or usage for users on the Apify free plan. If you choose to do this, you _must_ handle it transparently: + +- Communicate upfront: Clearly state any limitations in your Actor's `README` and input schema. Users should know about restrictions _before_ they run the Actor. +- Graceful exits: If a free user hits a limit, don't crash the Actor or return a system error. Instead, exit gracefully with a clear [status message](/platform/actors/development/programming-interface/status-messages#communicating-limitations) explaining the limit (e.g., "Free tier limit reached"). +- Avoid confusion: Never make a policy restriction look like a bug or platform error. + ## Actor analytics Monitor your Actors' performance through the [Actor Analytics](https://console.apify.com/actors/insights/analytics) dashboard under **Development > Insights > Analytics**. @@ -115,7 +123,7 @@ The analytics dashboard allows you to select specific Actors and view key metric All metrics can be exported as JSON for custom analysis and reporting. -## Promoting your Actor +## Promote your Actor Create search-engine-optimized descriptions and README files to improve search engine visibility. Share your Actor on multiple channels: