Add-ons

The add-on object

An add-on object represents an optional additional charge that can be made available on specific payment plans, then applied to subscriptions for your subscribers. An add-on can only be applied to a subscription if it is available on the payment plan the subscriber is being subscribed to.

The add-on stores a number of core attributes that apply to that additional optional charge for a subscriber to a payment plan, including:

• Basic information such as the name and description of the add-on.
• Whether the add-on has singular or multiple quantity functionality.
• Pricing information that determines the price for the add-on and whether the add-on is a one time or recurring charge.

// Example add-on object

{
  "id": 181,
  "dateCreated": "2024-06-05 14:59:30",
  "dateUpdated": "2024-06-05 15:22:06",
  "name": "Example Addon",
  "description": "Test",
  "amount": 10,
  "frequency": "recurring",
  "isQuantityEditable": true
 }

Adding an add-on to a subscription

Before applying an add-on to a subscription, that add-on first needs to be available to the payment plan object you intend to subscribe the customer to.

• An add-on can be made available on a payment plan through the Create payment plans and Patch payment plans endpoints, by passing an array of integers containing the relevant addOnIds.
• An add-on can then be applied to a subscription through the Create subscriptions or Link add-ons to a subscription endpoints, by passing an array of add-on objects with the addOnId and an optional quantity parameter for add-ons that support quantities.
• Once applied, add-ons will only charge with the subscriptions initial or subsequent recurring billing payments.

Add-on billing frequency

An add-on object can bill either one-time, or on a recurring basis, based on the value of the frequency parameter passed to the Create add-ons or Patch add-ons endpoints.

• A one_time add-on will bill once on the next recurring billing date for the subscription it is applied to.
• A recurring add-on will bill on every recurring billing date for the subscription it is applied to.

Add-on quantities

Each subscription can only have one of each unique addonId applied to it at a time.

If you wish to apply more than one of an add-on, the add-on should have an isQuantityEditable value of true. This will allow multiple quantities of an add-on to be applied for both one-time and recurring add-ons to a subscription.

Subscriptions than contain add-ons with an editable quantity, can have the quantity of the add-ons updated using the Patch subscription add-ons endpoint.

Removing an add-on from a subscription

An add-on that has been unlinked from a payment plan, will still charge subscribers whose subscriptions it has already been applied to, but it cannot be added to any new subscriptions to that payment plan.

To cease all billing of an add-on for subscribers of a payment plan, that add-on should be deleted from the subscription using either the Delete linked subscription add-ons or Delete a linked subscription add-on endpoints.

📘

After charging a one-time single application add-on, the Helcim system will remove the add-on from the subscription object automatically. The add-on can then be reapplied to the subscription after this point.

Add-on endpoints

Create, retrieve, update, and delete add-on objects using the following endpoints.