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
Parameter | Description | Options |
---|---|---|
timing | When changes apply | renewal (default): At next renewalimmediate : Apply right away |
billing_method | How to bill for additions | prorated (default): Bill for remaining timefull : Bill full amountno_billing : No charge for current periodzero_amount : Generate zero-amount invoice |
compensation_method | How to compensate for removals | no_compensation (default): No refund/creditprorated_refund : Refund for unused timefull_refund : Refund entire amountprorated_credit : Credit for unused timefull_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:
- Set
action
topause_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"
}
Recipe 2: Expire a Subscription
Ingredients:
- Subscription handle
- Execution date
- (Optional) Compensation method
Steps:
- Set
action
toexpire_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"
}
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:
- Set
action
toadd_addon_to_subscription
- Define the
execution_date
in the schedule - Specify the
subscription_handle
,addon_handle
, and a uniquehandle
- (Optional) Add customizations like
quantity
,amount
,timing
, andbilling_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:
- Set
action
toremove_addon_from_subscription
- Define the
execution_date
in the schedule - Specify the
subscription_handle
andaddon_handle
- (Optional) Add
timing
andcompensation_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:
- Set
action
toreactivate_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"
}
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