Subscribers

The subscription object

A subscription object represents a subscribers unique subscription to a payment plan. A single subscriber can be subscribed to multiple different payment plans and can even have multiple subscriptions to the same payment plan.

The subscription stores a number of core attributes to apply to that subscribers unique subscription to a plan, including:

• Subscription information such as recurring amount for that subscription and the customer that subscription is for.
• Subscription schedule information such as the number of billing cycles that subscriber will be charged and when their subscription will activate.
• Payment method information that determines whether the subscriber will pay using their default credit card or default ACH bank payment details.
• Payments and add-ons sub-objects for each payment processed or add-on linked for the subscription, returned in an array.

// Example susbcription object

{
  "id": 19980,
  "dateCreated": "2024-10-07 14:27:02",
  "dateUpdated": "0000-00-00 00:00:00",
  "dateActivated": "2024-10-07",
  "dateBilling": "2024-10-08",
  "status": "active",
  "paymentPlanId": 6395,
  "customerCode": "CST1044",
  "timesBilled": 1,
  "recurringAmount": 75,
  "freeTrialPeriod": 0,
  "hasFailedPayments": "no",
  "payments": [
    {
      "id": 90116,
      "setupAmount": 0,
      "recurringAmount": 75,
      "addOnAmount": 25,
      "amount": 75,
      "taxAmount": 5,
      "status": "approved",
      "dateDue": "2024-10-07 00:00:00",
      "dateProcessed": "2024-10-07 14:27:03",
      "paymentNumber": 1,
      "numberOfRetries": 0
    },
    {
      "id": 90117,
      "setupAmount": 0,
      "recurringAmount": 0,
      "addOnAmount": 0,
      "amount": 75,
      "taxAmount": 0,
      "status": "waiting",
      "dateDue": "2024-10-08 00:00:00",
      "dateProcessed": "0000-00-00 00:00:00",
      "paymentNumber": 2,
      "numberOfRetries": 0
    }
  ],
  "subscriptionAddOns": [
    {
      "addOnId": 429,
      "name": "One-Time Editable",
      "description": "One-time Editable Add-On Test",
      "amount": 25,
      "firstProcessedPaymentNumber": 1,
      "lastProcessedPaymentNumber": 1,
      "isActive": 0,
      "frequency": "one_time",
      "quantity": 1
    }
  ]
}

Subscribers payments

All subscription objects will store processed and waiting payments in the payments sub-object. Depending on the setup of your payment plans and subscribers, you may have a combination of one or more processed and waiting payments stored in your subscription object at any given time.

A payment will be processed either immediately or on a future date, based on a combination of the type of payment plan you are subscribing the customer to and the subscriptions activation date.

When subscribing a customer to a payment plan, the Helcim system will process due payments immediately and queue up future waiting payments, based on the following rules.

• The Helcim system will immediately bill payments where:
  • Any payment plan has a setupAmount and billSetupImmediately value of "immediate"
  • Any payment plans with a type of "subscription" to bill on sign-up, where the activationDate for the subscription is today
• The Helcim system will queue waiting payments where:
  • Any payment plan has either no setupAmount, or a setupAmount with a billSetupImmediately value of "first_billing"
  • Any payment plans with a type of "cycle" to bill on specific days, where the dateBilling for the subscription is not today

📘

Number of waiting payments created

The Helcim system may create all future payments or only the next future payment for a subscriber based on the following rules.

• If the subscription has a maxCycles value, indicating it expires after a set number of cycles, the Helcim system will create all future payments as it knows in advance how many payments to create.
• If the subscription does not have a maxCycles value, indicating it will continue indefinitely until cancelled, the Helcim system will create only the next payment as there is no known maximum number of payments to create.

Payment statuses

All payments contain a status parameter that identifies whether that payment has been processed and the outcome of that payment attempt, or whether that payment has been queued to process on a future date.

Recurring amounts

The recurringAmount parameter for a subscription plan determines the recurring amount to be charged to the customers default payment method on the billing date. This value can be different than the recurringAmount for the payment plan and is what the customer will be charged if different.

Capturing customer payment details

A subscription will always charge the subscribers default credit card or bank account in the Helcim system, depending on the payment method selected for them when setting them up as a subscriber to a payment plan.

To capture credit card or bank payment details for a new customer, or capture new payment details for an existing one, we recommend utilizing HelcimPay.js initialized with a paymentType of verify. This allows you to capture payment details in an easy and secure manner when your customer is making their plan selections through your website or application, or allow you to set new payment methods as default for future use.

• Read more on integrating with HelcimPay.js

To change the default between existing payment methods, for an existing subscriber, utilize the following endpoints to update the default payment for the respective customer object. Alternatively you can update the customers profile manually in the Customers section of your Helcim account.

• Set customer credit card as default
• Set customer bank account as default

Subscriber endpoints

Create, retrieve, update, and delete subscription objects, mark declined payments as paid, or link, update, and delete subscription add-ons using the following endpoints.