Payment plans

The payment plan object

A payment plan object represents the core element of a recurring service that one or more customers can be subscribed to through a subscription.

The payment plan stores a number of the core attributes that apply to subscribers to that plan, including:

• Basic information such as the unique name for the plan and plan description.
• Whether the payment plan has a trial period and whether subscriptions to that plan expire.
• Pricing information such as the one-time set up fees, the recurring amount to be charged, and the billing period.
• Billing schedule information such as the billing day and and how many billing periods the plan should bill for.
• Payment method and tax information that determines what payment methods subscribers can use to pay for that plan and how the Helcim system will calculate tax for the payments when they are processed.

// Example payment plan object

{
  "id": 6395,
  "dateCreated": "2024-10-04 09:19:16",
  "dateUpdated": "2024-10-04 15:31:13",
  "userId": 4279294,
  "name": "Test Payment Plan",
  "businessEmail": "",
  "businessName": "",
  "description": "Description of Payment Plan",
  "type": "subscription",
  "status": "active",
  "currency": "CAD",
  "cardTerminalId": 54181,
  "setupAmount": 0,
  "recurringAmount": 75,
  "billingPeriod": "daily",
  "billingPeriodIncrements": 1,
  "dateBilling": "Sign-up",
  "termType": "forever",
  "freeTrialPeriod": 0,
  "taxType": "customer",
  "termLength": 1,
  "paymentMethod": "card",
  "defaultPaymentLinkId": 0,
  "addOnIds": [
    429,
    430,
    431,
    432
  ]
}

Payment plan activation

A payment plan will always activate immediately on creation. In order to determine when subscribers to that plan will begin getting charged, you should control this by setting an appropriate activationDate for the customer's subscription object on creation.

Payment plan billing

A payment plan object contains information that determines a number billing behaviours for subscribers to that plan. The following are some of the important parameters, to understand how payment plans impact the billing of subscribers to that plan.

Payment plan billing type

The type parameter for a payment plan can be used to bill recurring amounts for subscribers to that plan immediately on sign-up, or on a specific date, based on the value passed.

Subscription

A subscription based payment plan is typically used when you wish to begin charging your customer for their subscription services right away. Each customers subscription to that payment plan can bill on a different dates but will recur at the same frequency.

• A type value of "subscription" will bill all subscribers to this payment plan on sign-up.
• The first recurring amount for a subscriber to this payment plan is processed on the subscriptions activation date.

📘

As an example, a payment plan could bill every 30 days from each customers unique subscription creation date.

Cycle

A cycle based payment plan is typically used when you wish to begin charging subscribers for their subscriptions to that plan on a specific date. Each subscribers subscription to that plan will bill initial and recurring amounts on the same date and will recur at the same frequency.

• A type value of "cycle" will bill all subscribers to this payment plan on a specific date.
• The first recurring amount for a subscriber to this payment plan is processed on the payment plans next billing date.

📘

As an example, a payment plan could bill monthly on the 1st of the month for every customer subscribed regardless of when the subscription was created.

Payment plan billing frequency

The payment plan type controls when the first recurring billing amount is charged to the customer.

The frequency with which subscribers to a payment plan will bill, can be controlled by a combination of parameters, including the billingPeriod, billingPeriodIncrements, and dateBilling.

Billing frequency

The billingPeriod and billingPeriodIncrements parameters can be combined to control how frequently subscribers to a payment plan will bill.

• The billingPeriod parameter controls whether subscribers to a payment plan bill on a daily, weekly, monthly, or yearly cadence.
• The billingPeriodIncrements parameter controls whether subscribers to a payment plan will bill on every single billing period, or if it will bill every X number of billing periods.

Some examples of this interaction would include:

• A payment plan with a billing period set to bill daily and an billing period increments set to 7, would bill subscribers to that plan every 7 days.
• A payment plan with a billing period set to monthly and a billing period increments set to 6, would bill subscribers to that plan every 6 months.

Billing date

The dateBilling value can be used to determine what date payment plans with a bill on specific date billing periods will charge subscribers to that plan.

• Payment plans with a bill on sign-up type, require a dateBilling of "Sign-up". The Helcim system will automatically set the dateBilling based on the billingPeriod and billingPeriodIncrements values selected for the payment plan.

You can control the billing date for payment plans with a type to bill on specific dates following a weekly, monthly, or yearly billingPeriod cadence, by using the following values in the dateBilling parameter.

• Payment plans with a daily billing period will by their nature bill daily, unless using a billingPeriodIncrements value to set the plan to bill every X number of days.
• Payment plans with a weekly billing period will bill weekly on the day passed in the dateBilling parameter. As an example, a value of "Monday" will result in the payment plan charging subscribers on Monday of every X number of weeks.
• Payment plans with a monthly billing period will bill monthly on the date passed in the dateBilling parameter. As an example, a value of 15 will result in the payment plan charging subscribers on the 15th day of every X number of months.
• Payment plans with a yearly billing period will bill yearly on the date passed in the dateBilling parameter. As an example, a value of 01-01 will result in the payment plans charging subscribers on January 1st every X number of years.

📘

The value of "X" in the above examples is controlled by the billingPeriodIncrements parameter.

Payment plan set up fees

Payment plans can have an optional one-time set up fee. This fee can be charged to customers subscribing to that plan on their first billing date or immediately.

• Configuring a set up fee requires a setupAmount and billSetupImmediately parameter.
• If a set up fee is set to "immediate", this will allow you to charge the customer a one-time fee on subscription creation, even if the recurring charges for the plan do not bill on sign-up.

Payment plan term types

Payment plans control whether subscribers to that plan can have a set number of maximum recurring cycles they will bill for, or if they can bill indefinitely until they are made inactive.

• A termType value of "forever" will allow you to create subscriptions to this plan that do not have a maximum number of billing cycles and will bill indefinitely until they are made inactive.
• A termType value of "expires" will allow you to create subscriptions to this plan that will charge for a maximum number of billing cycles until they automatically become inactive. As an example, a subscription with a maxCycles of 12 on a payment plan set to bill monthly, will charge the customer for 12 months before becoming inactive.

🚧

Every subscriber to a payment plan will need to adhere to that payment plans termType setting.

You cannot add an expiring subscription to an infinitely billed payment plan, nor an infinite subscription to a payment plan with a set number of billing cycles.

Payment plan tax types

Payment plans control how subscriptions to that plan will bill taxes for their set-up and recurring payments. This is controlled through the taxType parameter and can have three potential options.

• no_tax: No taxes will be applied to subscriptions to the plan.
• customer: Subscriptions to the plan tax according to customer's location. This requires the customer object to have a valid country and state / province stored.
• merchant: Subscriptions to the plan tax according to your businesses' location.

📘

Taxes are calculated at time of processing. Please note that any waiting payments for a subscriber will not reflect relevant taxes until after processing.

Payment plan add-ons

In order to apply an add-on to a customers subscription, it must first be available for the payment plan.

You can link add-ons to a payment plan through the Create payment plans and Patch payment plans endpoints by passing an array of integers for the addOnIds.

📘

Add-ons linked to payment plans will not automatically apply to any subscribers to that plan.

An add-on must be added when subscribing a customer to a plan, using the Create subscriptions or Patch subscriptions endpoints.

Payment plan endpoints

Create, retrieve, update, and delete payment plan objects using the following endpoints.