🚧
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

This endpoint allows you to create a new action in the Rule Engine that will be executed at a specified time in the future. Actions provide automated control over subscription management, enabling you to schedule changes to subscriptions based on your business requirements.

Common Parameters

Several action types share common parameters that control how and when changes are applied to subscriptions:

Timing

The timing parameter defines when a change will be applied to a subscription after the action is executed:

renewal: (Default) The change will be applied at the next subscription renewal date. This is the least disruptive option as it doesn't affect the current billing period.
immediate: The change will be applied immediately after the action is executed. This option may trigger immediate billing or compensation depending on the action type.

Billing Method

The billing_method parameter controls how a customer is billed when an action results in additional charges (e.g., when adding an add-on or reactivating a subscription):

prorated: (Default) The customer is charged a prorated amount based on the remaining time in the current billing period. For example, if half the billing period remains, the customer is charged half the normal price.
full: The customer is charged the full amount regardless of when in the billing period the change occurs.
no_billing: No billing occurs for the remainder of the current period. The customer will be billed normally starting from the next period.
zero_amount: A zero-amount invoice is generated to record the change, but no actual billing occurs.

Compensation Method

The compensation_method parameter determines how a customer is compensated when an action results in a reduction of service (e.g., when removing an add-on, pausing or expiring a subscription):

no_compensation: (Default for most actions) No compensation is provided to the customer.
prorated_refund: The customer receives a refund proportional to the unused portion of the current billing period. For example, if half the billing period remains, the customer receives a refund for half the amount paid.
full_refund: The customer receives a full refund for the current billing period, regardless of how much time has elapsed.
prorated_credit: The customer receives account credit proportional to the unused portion of the current billing period. This credit can be applied to future invoices.
full_credit: The customer receives account credit for the full amount of the current billing period, regardless of how much time has elapsed.

Base Action Structure

All actions share a common base structure:

{
    "action": "action_type",
    "schedule": {
        "execution_date": "2023-12-01T10:00:00Z"
    },
    // Action-specific properties
}

Where:

action: The type of action to perform (required)
schedule: Scheduling settings for the action (required)
- execution_date: The date and time when the action should be executed (conditionally required, ISO-8601 format)
- event_type: Alternatively to the execution_date above, you may specify an event type instead which will trigger the action. This is useful for scenarios where you do not know the exact date and time when the action should be executed (conditionally required, allowed values: subscription_contract_period_renewed)

Action Types

The Rule Engine supports the following action types for subscriptions:

Action 1: Pause Subscription

Allows scheduling a subscription pause for a future date.

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

Required fields:

action: Must be "pause_subscription"
schedule: Scheduling settings
subscription_handle: Handle of the subscription which will be paused

Optional fields:

compensation_method: Compensation method to use when pausing the subscription
- Available options: "full_refund" (refund entire amount), "prorated_refund" (refund based on unused time), "full_credit" (credit entire amount), "prorated_credit" (credit based on unused time), "no_compensation" (no refund or credit)
- Default: "no_compensation"
reactivation_configuration: Configuration for automatic reactivation after the pause period
- reactivate_at: Date and time when the subscription will be automatically reactivated (ISO-8601 format, must be in the future)
- billing_method: Billing method to use when reactivating ("full", "prorated", "no_billing", "zero_amount")

Example with automatic reactivation:

{
    "action": "pause_subscription",
    "schedule": {
        "execution_date": "2023-12-01T10:00:00Z"
    },
    "subscription_handle": "sub-1234567890",
    "compensation_method": "prorated_refund",
    "reactivation_configuration": {
        "reactivate_at": "2024-01-01T10:00:00Z",
        "billing_method": "prorated"
    }
}

Action 2: Reactivate Subscription

Schedules reactivation of a previously paused subscription for a future date.

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

Required fields:

action: Must be "reactivate_subscription"
schedule: Scheduling settings
subscription_handle: Handle of the subscription which will be reactivated

Optional fields:

billing_method: Billing method for the action
- Available options: "full" (charge full amount), "prorated" (charge based on remaining time), "no_billing" (no charge for current period), "zero_amount" (generate zero-amount invoice)
- Default: "prorated"

Action 3: Expire Subscription

Schedules the expiration of a subscription at a future date. This action is irreversible once executed.

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

Required fields:

action: Must be "expire_subscription"
schedule: Scheduling settings
subscription_handle: Handle of the subscription which will be expired

Optional fields:

compensation_method: Compensation method to use when expiring the subscription
- Available options: "full_refund" (refund entire amount), "prorated_refund" (refund based on unused time), "no_compensation" (no refund)
- Default: "no_compensation"

Action 4: Add Add-on to Subscription

Schedules the addition of an add-on to a subscription at a future date.

{
    "action": "add_addon_to_subscription",
    "schedule": {
        "execution_date": "2023-12-01T10:00:00Z"
    },
    "subscription_handle": "sub-1234567890",
    "addon_handle": "addon-premium",
    "handle": "sub002-addon001",
    "quantity": 3,
    "amount": 20000,
    "description": "Special price given to vip customer",
    "timing": "immediate",
    "fixed_amount": true,
    "amount_incl_vat": false,
    "billing_method": "prorated"
}

Required fields:

action: Must be "add_addon_to_subscription"
schedule: Scheduling settings
subscription_handle: Subscription handle where the addon will be added
addon_handle: Addon handle to be added to the subscription
handle: Per subscription unique handle for the subscription add-on

Optional fields:

quantity: Quantity of the add-on for this subscription (default: 1, minimum: 1)
amount: Custom fixed per quantity add-on price (minimum: 0)
description: Description overriding the add-on description
timing: When the change will be applied to the subscription
- Available options: "immediate" (apply changes right away), "renewal" (apply at next renewal)
- Default: "renewal"
fixed_amount: Whether the price should be fixed to the current price of add-on (default: true)
amount_incl_vat: Whether the optional amount is including VAT (default: true)
billing_method: Billing method for the add-on
- Available options: "full" (charge full amount), "prorated" (charge based on remaining time), "no_billing" (no charge for current period), "zero_amount" (generate zero-amount invoice)
- Default: "prorated"

Action 5: Remove Add-on from Subscription

Schedules the removal of an add-on from a subscription at a specified future date.

{
    "action": "remove_addon_from_subscription",
    "schedule": {
        "execution_date": "2023-12-01T10:00:00Z"
    },
    "subscription_handle": "sub-1234567890",
    "addon_handle": "addon-premium",
    "timing": "immediate",
    "compensation_method": "prorated_refund",
    "billing_method": "prorated"
}

Required fields:

action: Must be "remove_addon_from_subscription"
schedule: Scheduling settings
subscription_handle: Subscription handle where the addon will be removed
addon_handle: Addon handle to be removed from the subscription

Optional fields:

timing: When the change will be applied to the subscription
- Available options: "immediate" (remove right away), "renewal" (remove at next renewal)
- Default: "renewal"
compensation_method: Compensation method to use when removing the addon
- Available options: "full_refund" (refund entire amount), "prorated_refund" (refund based on unused time), "full_credit" (credit entire amount), "prorated_credit" (credit based on unused time), "no_compensation" (no refund or credit)
- Default: "prorated_refund"

Action 6: Change Amount on Subscription Plan

Schedules a change to the amount of a subscription plan at a specified future date. This action modifies the plan pricing and can optionally apply the change to existing subscriptions.

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

Required fields:

action: Must be "change_amount_on_subscription_plan"
schedule: Scheduling settings
plan_handle: Handle of the subscription plan to change the amount for
amount: New amount for the subscription plan in minor currency units (minimum: 0)

Optional fields:

apply_to_existing_subscriptions: Whether to apply the amount change to existing subscriptions
- If true: Existing subscriptions using this plan will be updated with the new amount on their next renewal
- If false: Only new subscriptions will use the new amount
- Default: false

Important notes:

The amount is specified in minor currency units. For example, 25000 represents $250.00 for USD
When applying changes to existing subscriptions, the timing and billing impact depends on each subscription's current state and billing cycle

Action 7: Change Subscription Plan

Schedules a plan change for a subscription at a specified future date. This action changes the subscription to use a different plan while maintaining the subscription's continuity.

{
    "action": "change_plan_on_subscription",
    "schedule": {
        "execution_date": "2023-12-01T10:00:00Z"
    },
    "subscription_handle": "sub-1234567890",
    "new_plan_handle": "plan-premium",
    "timing": "renewal",
    "compensation_method": "prorated_refund",
    "billing_method": "prorated"
}

Required fields:

action: Must be "change_plan_on_subscription"
schedule: Scheduling settings
subscription_handle: Handle of the subscription to change the plan for
new_plan_handle: Handle of the new plan that the subscription will be changed to

Optional fields:

timing: When the change will be applied to the subscription after the action is executed
- Available options: "immediate" (apply immediately), "renewal" (apply at next renewal)
- Default: "renewal"
compensation_method: Compensation method to use when changing the subscription plan
- Available options: "full_refund" (refund entire amount), "prorated_refund" (refund based on unused time), "full_credit" (credit entire amount), "prorated_credit" (credit based on unused time), "no_compensation" (no refund or credit)
- Default: "prorated_refund"
billing_method: Billing method to use when changing the plan with immediate timing
- Available options: "full" (charge full amount), "prorated" (charge based on remaining time), "no_billing" (no charge for current period), "zero_amount" (generate zero-amount invoice)
- Default: "prorated"

Important notes:

Plan changes can result in both upgrades and downgrades
For immediate changes, ensure you review any potential impacts and choose the appropriate compensation and billing methods

Action 8: Change Subscription Notice Period

Schedules a change for the notice period of a subscription at a specified future date or event.

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

Required fields:

action: Must be "change_subscription_notice_period"
schedule: Scheduling settings
subscription_handle: Handle of the subscription to change the notice period for
new_notice_period: Number of periods for the new notice period. Must be a positive number larger than 0
new_notice_period_unit: Unit of the new_notice_period. Allowed values: day, weeek, month, year

Optional fields:

timing: When the change will be applied to the subscription after the action is executed
- Available options: "immediate" (apply immediately), "renewal" (apply at next renewal)
- Default: "renewal"

Response

When an action is successfully created, the API returns a response with details about the created action:

{
  "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"
}

Where:

id: The unique identifier for the created action
state: The current state of the action (new, success, failure, retrying, nothing_to_do)
created: Timestamp when the action was created
details: Action-specific details
action: The type of action
schedule: The scheduling settings for the action
entity_id: The ID of the entity on which the action is performed
entity_type: The type of entity on which the action is performed

Related Endpoints

Get Action List