🚧
Preview Status
All Rule Engine actions are currently in PREVIEW phase. When creating actions:

Monitor action execution results

Review scheduled actions regularly

Report any issues encountered to our support team

Overview

The Rule Engine API provides automation capabilities for subscription management through scheduled actions. This feature allows you to automate various modifications on different product types by scheduling them for future execution.

Quick Reference

Common Parameters

Parameter	Description	Options
`timing`	When changes apply	`renewal` (default): At next renewal `immediate`: Apply right away
`billing_method`	How to bill for additions	`prorated` (default): Bill for remaining time `full`: Bill full amount `no_billing`: No charge for current period `zero_amount`: Generate zero-amount invoice
`compensation_method`	How to compensate for removals	`no_compensation` (default): No refund/credit `prorated_refund`: Refund for unused time `full_refund`: Refund entire amount `prorated_credit`: Credit for unused time `full_credit`: Credit entire amount

Base Structure

All actions follow this pattern:

{
  "action": "action_type",
  "schedule": {
    "execution_date": "YYYY-MM-DDThh:mm:ssZ",
      // OR
      "event_type": "subscription_contract_period_renewed"
  }
  // Action-specific properties
}

Action Recipes

Action 1: Pause a Subscription

Ingredients:

Subscription handle
Execution date
(Optional) Compensation method

Steps:

Set action to pause_subscription
Define the execution_date in the schedule
Specify the subscription_handle
(Optional) Add compensation_method if you want to refund or credit the customer

Minimal Example:

{
  "action": "pause_subscription",
  "schedule": {
    "execution_date": "2023-12-01T10:00:00Z"
  },
  "subscription_handle": "sub-1234567890"
}

Action 2: Expire a Subscription

Ingredients:

Subscription handle
Execution date
(Optional) Compensation method

Steps:

Set action to expire_subscription
Define the execution_date in the schedule
Specify the subscription_handle
(Optional) Add compensation_method if you want to refund or credit the customer

Minimal Example:

{
  "action": "expire_subscription",
  "schedule": {
    "execution_date": "2023-12-01T10:00:00Z"
  },
  "subscription_handle": "sub-1234567890"
}

Action 3: Add an Add-on to a Subscription

Ingredients:

Subscription handle
Add-on handle
Unique handle for this subscription add-on
Execution date
(Optional) Quantity, amount, timing, billing method

Steps:

Set action to add_addon_to_subscription
Define the execution_date in the schedule
Specify the subscription_handle, addon_handle, and a unique handle
(Optional) Add customizations like quantity, amount, timing, and billing_method

Minimal Example:

{
  "action": "add_addon_to_subscription",
  "schedule": {
    "execution_date": "2023-12-01T10:00:00Z"
  },
  "subscription_handle": "sub-1234567890",
  "addon_handle": "addon-premium",
  "handle": "sub002-addon001"
}

Action 4: Remove an Add-on from a Subscription

Ingredients:

Subscription handle
Add-on handle
Execution date
(Optional) Timing, compensation method

Steps:

Set action to remove_addon_from_subscription
Define the execution_date in the schedule
Specify the subscription_handle and addon_handle
(Optional) Add timing and compensation_method to control when and how the customer is compensated

Minimal Example:

{
  "action": "remove_addon_from_subscription",
  "schedule": {
    "execution_date": "2023-12-01T10:00:00Z"
  },
  "subscription_handle": "sub-1234567890",
  "addon_handle": "addon-premium"
}

Action 5: Reactivate a Subscription

Ingredients:

Subscription handle
Execution date
(Optional) Billing method

Steps:

Set action to reactivate_subscription
Define the execution_date in the schedule
Specify the subscription_handle
(Optional) Add billing_method to control how the customer is billed for the reactivation

Minimal Example:

{
  "action": "reactivate_subscription",
  "schedule": {
    "execution_date": "2023-12-01T10:00:00Z"
  },
  "subscription_handle": "sub-1234567890"
}

Action 6: Change Amount on a Plan

Ingredients:

Plan handle
New amount (in minor currency units)
Execution date
(Optional) Apply to existing subscriptions

Steps:

Set action to change_amount_on_subscription_plan
Define the execution_date in the schedule
Specify the plan_handle and new amount
(Optional) Set apply_to_existing_subscriptions to update existing subscriptions with the new amount on their next renewal

Minimal Example:

{
  "action": "change_amount_on_subscription_plan",
  "schedule": {
    "execution_date": "2023-12-01T10:00:00Z"
  },
  "plan_handle": "plan-1234567890",
  "amount": 25000
}

Action 7: Change Plan in a Subscription

Ingredients:

Subscription handle
New plan handle
Execution date
(Optional) Timing, compensation method, billing method

Steps:

Set action to change_plan_on_subscription
Define the execution_date in the schedule
Specify the subscription_handle and new_plan_handle
(Optional) Add timing, compensation_method, and billing_method to control when and how the change is applied

Minimal Example:

{
  "action": "change_plan_on_subscription",
  "schedule": {
    "execution_date": "2023-12-01T10:00:00Z"
  },
  "subscription_handle": "sub-1234567890",
  "new_plan_handle": "plan-premium"
}

Action 8: Change Notice Period of a Subscription

Ingredients:

Subscription handle
New notice period
(Optional) timing

Steps:

Set action to change_subscription_notice_period
Define the execution_date or event_type in the schedule
Specify the subscription_handle as well as new_notice_period and new_notice_period_unit
(Optional) Set timing to renewal or immediate (defaults to renewal)

Minimal Example:

{
  "action": "change_plan_on_subscription",
  "schedule": {
    "event_type": "subscription_contract_period_renewed"
  },
  "subscription_handle": "sub-1234567890",
  "new_notice_period": 1,
  "new_notice_period_unit": "week"
}

What to Expect in Response

When you successfully create an action, you'll receive a response like this:

{
  "id": "action-1234567890",
  "state": "new",
  "created": "2023-12-01T10:00:00Z",
  "details": {
    // Action-specific details
  },
  "action": "add_addon_to_subscription",
  "schedule": {
    "execution_date": "2023-12-01T10:00:00Z"
  },
  "entity_id": "sub-1234567890",
  "entity_type": "subscription"
}

The state field will initially be new and will change to success, failure, retrying, or nothing_to_do after execution.

Important Considerations

When working with Rule Engine actions:

Modifications are treated as merchant-initiated changes
For detailed parameter descriptions, refer to the Create Action documentation

Available Endpoints

Create Action: Schedule new subscription modifications
Get Action List: View and monitor scheduled actions
Get Action by Handle: Retrieve a specific action by its handle