Actions

Manage automated product modifications through the Rule Engine

🚧

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

ParameterDescriptionOptions
timingWhen changes applyrenewal (default): At next renewal
immediate: Apply right away
billing_methodHow to bill for additionsprorated (default): Bill for remaining time
full: Bill full amount
no_billing: No charge for current period
zero_amount: Generate zero-amount invoice
compensation_methodHow to compensate for removalsno_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"
  },
  // Action-specific properties
}

Action Recipes

Recipe 1: Pause a Subscription

Ingredients:

  • Subscription handle
  • Execution date
  • (Optional) Compensation method

Steps:

  1. Set action to pause_subscription
  2. Define the execution_date in the schedule
  3. Specify the subscription_handle
  4. (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"
}

Recipe 2: Expire a Subscription

Ingredients:

  • Subscription handle
  • Execution date
  • (Optional) Compensation method

Steps:

  1. Set action to expire_subscription
  2. Define the execution_date in the schedule
  3. Specify the subscription_handle
  4. (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"
}

Recipe 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:

  1. Set action to add_addon_to_subscription
  2. Define the execution_date in the schedule
  3. Specify the subscription_handle, addon_handle, and a unique handle
  4. (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"
}

Recipe 4: Remove an Add-on from a Subscription

Ingredients:

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

Steps:

  1. Set action to remove_addon_from_subscription
  2. Define the execution_date in the schedule
  3. Specify the subscription_handle and addon_handle
  4. (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"
}

Recipe 5: Reactivate a Subscription

Ingredients:

  • Subscription handle
  • Execution date
  • (Optional) Billing method

Steps:

  1. Set action to reactivate_subscription
  2. Define the execution_date in the schedule
  3. Specify the subscription_handle
  4. (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"
}

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