## 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. ```json // Example subscription 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. Once the subscription runs on its billing date and processes a transaction, we create a `transaction` object that is independent of the subscription and it's `payment` sub-object. 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.

`status`	Description
`approved`	Approved payments are payments that have been processed successfully.
`declined`	Declined payments are payments that have been attempted but failed due to a "soft" decline reason, such as insufficient funds. that have been attempted. Attempt these payments again using the [Process a subscription payment](https://devdocs.helcim.com/v2.2/reference/procedure-process-payment) procedure endpoint. If declines persist you should connect with your customer to obtain updated payment information.
`failed`	Failed payments are payments that have been attempted but failed due to a "hard" decline reason, such as invalid card data, invalid subscription data, or expired cards. Update the customers billing information before attempting these payments again using the [Process a subscription payment](https://devdocs.helcim.com/v2.2/reference/procedure-process-payment) procedure endpoint.
`waiting`	Waiting payments that are queued for future dates. These payments will have a `dateProcessed` of "0000-00-00 00:00:00".

### 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](https://devdocs.helcim.com/docs/overview-of-helcimpayjs/) 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](https://devdocs.helcim.com/v2.2/reference/setcustomercarddefault#/) * [Set customer bank account as default](https://devdocs.helcim.com/v2.2/reference/setcustomerbankaccountdefault#/) ### Retrieving subscription payment details If you're looking for more information on a subscriptions payments, or you're looking to reconcile transactions, then we have a few different endpoints available to gather the information you need and find your `payment` sub-objects or `transaction` objects. You can call the Get subscription collection endpoint that returns all of your subscription objects. Is this object, you have a number of parameters, such as which customer it is for through `customerCode`, the number of times it has billed through `timesBilled`, and the date it bills through `dateBilling`. * [Get subscription collection](https://devdocs.helcim.com/v2.2/reference/subscriptions-collection#/) ```json // Example subscription object { "id": 19849, "dateCreated": "2024-10-04 09:28:19", "dateUpdated": "0000-00-00 00:00:00", "dateActivated": "2024-10-04", "dateBilling": "2025-03-06", "status": "active", "paymentPlanId": 6395, "customerCode": "CST1044", "timesBilled": 118, "setupAmount": 0, "recurringAmount": 75, "freeTrialPeriod": 0, "hasFailedPayments": "true", "isProrated": "no", "addOnsIds": [ 741, 742 ] } ``` Once you have collected your subscriptions, you can take the `id` and retrieve the subscription and it's payment sub-objects through the Get subscription endpoint. The payment sub-object gives you a status of the payment, the amount, and other information to verify the outcome of the payment. * [Get subscription](https://devdocs.helcim.com/v2.2/reference/subscription-single#/) ```json // Example subscription with a payment sub-object { "id": 19849, "dateCreated": "2024-10-04 09:28:19", "dateUpdated": "0000-00-00 00:00:00", "dateActivated": "2024-10-04", "dateBilling": "2025-03-06", "status": "active", "paymentPlanId": 6395, "customerCode": "CST1044", "timesBilled": 118, "setupAmount": 0, "recurringAmount": 75, "freeTrialPeriod": 0, "hasFailedPayments": "true", "isProrated": "no", "payments": [ { "id": 89338, "setupAmount": 0, "recurringAmount": 75, "addOnAmount": 0, "amount": 75, "taxAmount": 3.75, "status": "approved", "dateDue": "2024-10-04 00:00:00", "dateProcessed": "2024-10-04 09:28:20", "paymentNumber": 1, "numberOfRetries": 0 } } ``` If you need to also reconcile this with the transaction object, then you can compare a number of parameters to the transaction object in order to determine if that transaction is associated to that specific subscription and payment. If you go to the Get card transactions endpoint you can retrieve `transaction` objects for the specific customer, on a specific date, then with this request you will receive the specific transaction object associated with that customer, subscription, and payment. For credit card payments, this can be done with the `customerCode`, `dateFrom`, and `dateTo` parameters. For ACH payments, we do not currently have query parameters in our Get ACH transactions endpoint, so you would want to search through the returned payments looking for these values. * [Get card transactions](https://devdocs.helcim.com/v2.2/reference/getcardtransactions#/) * [Get ACH transactions](https://devdocs.helcim.com/v2.2/reference/getmanyachtransactions#/) ```json // Example credit card transaction object for the subscription payment { "transactionId": 29032084, "dateCreated": "2024-10-04 09:28:20", "cardBatchId": 3999899, "status": "APPROVED", "user": "", "type": "purchase", "amount": 78.75, "currency": "CAD", "avsResponse": "X", "cvvResponse": "", "cardType": "MC", "approvalCode": "T1E5ST", "cardToken": "5823c2887463c485c2789f", "cardNumber": "5454545454", "cardHolderName": "John Doe", "customerCode": "CST1044", "invoiceNumber": "INV_SUB49", "warning": "" } ``` ## 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. | Endpoint | Description | | :----------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Get subscription collection](https://devdocs.helcim.com/v2.2/reference/subscriptions-collection) | Retrieve an array of subscriptions that match a wide range of query parameters. | | [Patch subscriptions](https://devdocs.helcim.com/v2.2/reference/subscription-patch) | Partially update one or more subscriptions. | | [Create subscriptions](https://devdocs.helcim.com/v2.2/reference/subscription-create) | Create one or more subscriptions to your payment plans. | | [Delete subscription](https://devdocs.helcim.com/v2.2/reference/subscription-delete) | Delete a single subscription by its `id`. | | [Get subscription](https://devdocs.helcim.com/v2.2/reference/subscription-single) | Retrieve a single subscription by its `id`, including any sub-objects, such as payments processed for that subscription or add-ons applied to that subscription. | | [Delete linked subscription add-ons](https://devdocs.helcim.com/v2.2/reference/subscription-add-on-delete) | Delete all linked subscription add-ons from a single subscription. This will delete the add-ons as a sub-object from the subscription, but not delete the `add-on` object itself. To delete an `add-on` object, use the [Delete add-on](https://devdocs.helcim.com/v2.2/reference/add-on-delete) endpoint. | | [Patch subscription add-ons](https://devdocs.helcim.com/v2.2/reference/subscription-add-on-patch) | Partially update the quantities for one or more subscription `add-on` sub-objects. The add-on must support quantities. To allow an add-on to support quantities, use the [Patch add-ons](https://devdocs.helcim.com/v2.2/reference/add-on-patch) endpoint. | | [Link add-ons to a subscription](https://devdocs.helcim.com/v2.2/reference/subscription-add-on-create) | Link one or more add-ons to a subscription. | | [Delete a linked subscription add-on](https://devdocs.helcim.com/v2.2/reference/subscription-add-on-single-delete) | Delete a single linked subscription add-on from a single subscription. This will delete the add-on as a sub-object from the subscription, but not delete the `add-on` object itself. To delete an `add-on` object, use the [Delete add-on](https://devdocs.helcim.com/v2.2/reference/add-on-delete) endpoint. | | [Mark payment paid](https://devdocs.helcim.com/v2.2/reference/subscription-payment-patch) | Update a single declined subscription payment to approved when payment was collected externally from the Helcim system (e.g. Cash or Cheque). To process a failed subscription payment using Credit Card or ACH payment, use the [Process a subscription payment](https://devdocs.helcim.com/v2.2/reference/procedure-process-payment) procedure endpoint. |