apify · vdusek · May 22, 2026 · May 21, 2026 · May 22, 2026 · May 22, 2026
@@ -1,13 +1,27 @@
 title: ActorChargeEvent
+description: |
+  Definition of a single chargeable event for a pay-per-event Actor. Each event is either flat-priced
+  (`eventPriceUsd` is set) or tier-priced (`eventTieredPricingUsd` is set); the two are mutually exclusive.
 type: object
 required:
-  - eventPriceUsd
   - eventTitle
   - eventDescription
 properties:
-  eventPriceUsd:
-    type: number
   eventTitle:
     type: string
+    description: Human-readable title shown to users in the billing UI.
   eventDescription:
     type: string
+    description: Human-readable description of what triggers this event.
+  eventPriceUsd:
+    type: number
+    description: |
+      Flat price per event in USD. Present only for non-tiered events. Mutually exclusive with `eventTieredPricingUsd`.
+  eventTieredPricingUsd:
+    $ref: ./TieredPricingPerEvent.yaml
+  isPrimaryEvent:
+    type: boolean
+    description: Whether this event is the Actor's primary chargeable event.
+  isOneTimeEvent:
+    type: boolean
+    description: Whether this event can only be charged once per Actor run.
@@ -27,3 +27,9 @@ properties:
   reasonForChange:
     type: [string, "null"]
     x-internal: true
+  isPriceChangeNotificationSuppressed:
+    type: boolean
+    x-internal: true
+  forceContainsSignificantPriceChange:
+    type: boolean
+    x-internal: true
@@ -4,7 +4,6 @@ allOf:
   - type: object
     required:
       - pricingModel
-      - pricePerUnitUsd
       - unitName
     properties:
       pricingModel:
@@ -15,3 +14,8 @@ allOf:
         description: Name of the unit that is being charged
       pricePerUnitUsd:
         type: number
+        description: |
+          Price per unit in USD. Mutually exclusive with `tieredPricing` - exactly one of the two is present
+          on a pricing record.
+      tieredPricing:
+        $ref: ./TieredPricingPerDatasetItem.yaml
@@ -0,0 +1,7 @@
+title: TieredPricingPerDatasetItem
+description: |
+  Tiered price-per-dataset-item pricing, keyed by subscription tier (e.g. `FREE`, `BRONZE`, `SILVER`, `GOLD`,
+  `PLATINUM`, `DIAMOND`). The actual price applied to a run is resolved from the user's tier.
+type: object
+additionalProperties:
+  $ref: ./TieredPricingPerDatasetItemEntry.yaml
@@ -0,0 +1,9 @@
+title: TieredPricingPerDatasetItemEntry
+description: A single tier's price-per-dataset-item entry.
+type: object
+required:
+  - tieredPricePerUnitUsd
+properties:
+  tieredPricePerUnitUsd:
+    type: number
+    description: Price per unit in USD for this tier.
@@ -0,0 +1,7 @@
+title: TieredPricingPerEvent
+description: |
+  Tiered price-per-event pricing for a single charge event, keyed by subscription tier (e.g. `FREE`, `BRONZE`,
+  `SILVER`, `GOLD`, `PLATINUM`, `DIAMOND`). The actual price applied is resolved from the user's tier.
+type: object
+additionalProperties:
+  $ref: ./TieredPricingPerEventEntry.yaml
@@ -0,0 +1,9 @@
+title: TieredPricingPerEventEntry
+description: A single tier's price-per-event entry.
+type: object
+required:
+  - tieredEventPriceUsd
+properties:
+  tieredEventPriceUsd:
+    type: number
+    description: Price per event in USD for this tier.
@@ -11,8 +11,8 @@ properties:
     description: The name of the Actor.
   version:
     type: string
-    pattern: ^[0-9]+\.[0-9]+$
-    description: The version of the Actor, specified in the format [Number].[Number], e.g., 0.1, 1.0.
+    pattern: ^[0-9]+(\.[0-9]+)+$
+    description: The version of the Actor, typically a dot-separated sequence of numbers (e.g., `0.1`, `1.0`, or `0.0.1`).
   buildTag:
     type: string
     description: The tag name to be applied to a successful build of the Actor. Defaults to 'latest' if not specified.