Billwerk+ is now Frisbii
API Reference
Frisbii WebsiteKnowledge BaseTry for freeBook a demo

Create Action

post https://rule-engine-api.frisbii.com/v1/action

Create a new scheduled action in 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

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 (required, ISO-8601 format)

Action Types

The Rule Engine supports the following action types for subscriptions:

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"

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"

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), "full_credit" (credit entire amount), "prorated_credit" (credit based on unused time), "no_compensation" (no refund or credit)
    • Default: "no_compensation"

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",
    "compensation_method": "prorated_refund"
}

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"
  • compensation_method: Compensation method to use when adding 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"

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"
  • billing_method: Billing method to use when removing the addon
    • Available options: "prorated" (charge based on time used), "immediate" (apply changes immediately)
    • Default: "prorated"

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

Language
Credentials
Basic
base64
:
Click Try It! to start a request and see the response here!