Sign in

v1

latestOpenAPI 3.0.02026-07-2671142187.3 KB
Payment Plans

Get payment plan collection

Query all payment plans filtered by the provided parameters

get/payment-plans

Query parameters

idinteger

The payment plan id

namestring

Given payment plan name. Only exact matches are currently supported.

type'subscription' | 'cycle'

The payment plan billing type:

  • subscription - On sign-up plan bills on subscription activation date
  • cycle - Pick a day plans bill on specific days
status'active' | 'inactive'

The payment plan activity status:

  • active - Status value for active plans
  • inactive - Status value for inactive plans
currency'CAD' | 'USD'

The currency subscriptions to the payment plan are billed with. Both CAD and USD are only applicable to Canadian merchants.

  • CAD - Canadian Dollars
  • USD - American Dollars
setupAmountnumber float

The monetary amount charged at time of sign-up for subscriptions to the payment plan

recurringAmountnumber float

The recurring monetary amount charged for subscriptions to the payment plan

billingPeriod'daily' | 'weekly' | 'monthly' | 'yearly'

The cycle at which subscriptions to the payment plan are billed:

  • daily - Cycle value for plans billed daily
  • weekly - Cycle value for plans billed weekly
  • monthly - Cycle value for plans billed monthly
  • yearly - Cycle value for plans billed yearly
billingPeriodIncrementsinteger

The frequency to which subscriptions for the payment plan are processed based on billing period.

  • 1 - Monthly plan will bill every month based on the scheduled billing day.
  • 2 - Yearly plan will bill every two years, or a weekly plan every 2 weeks.
  • 3 - Monthly plan will be billed quarterly.
  • 4 - Weekly plan will bill every 4 weeks.
  • 30 - Daily plan will bill every 30 days.
dateBillingstring

The date subscriptions to the payment plan are billed. This field requires specific formatting depending on the plan's billing cycle. See below examples for required formats:

  • Sign-up - Stored billing date for on sign-up plans
  • Daily - Stored billing date for plans billing daily
  • Monday - Weekly billing plans billing on a specific day store their billing day as the weekday name
  • 08 - Monthly billing plans billing on a specific day store their billing day in DD format
  • 06-15 - Yearly billing plans billing on a specific day store their billing day in MM-DD format
termType'forever' | 'expires'

Identifies whether subscriptions to the plan expire after a set number of billings:

  • forever - Value for plans whose subscriptions do not expire
  • expires - Value for plans whose subscriptions expire after a set number of billings
freeTrialPeriodinteger

Free trial length (in days) for subscriptions to the payment plan

taxType'no_tax' | 'customer' | 'merchant'

The tax rate applied to subscriptions to the payment plan:

  • no_tax - No taxes applied to subscriptions to the plan
  • customer - Subscriptions to the plan tax according to the customer's location
  • merchant - Subscriptions to the plan tax according to your business' location
taxCalculation'country_only' | 'country_province' | 'province_only'

The specific country and province/state tax(es) applied to the tax rate calculation:

  • country_only - country tax applied only
  • country_province - summed total of country and province/state taxes applied
  • province_only - province/state tax applied only
paymentMethod'card' | 'bank' | 'card_bank'

The allowed payment methods subscriptions to this plan can utilize:

  • card - Subscriptions to plan bill via credit card
  • bank - Subscriptions to the plan bill via ACH
  • card_bank - Subscriptions to the plan can bill via either credit card or ACH
addOnIdinteger

Add-on linked to the payment plan

sortBy'asc' | 'desc'

Sorting preference of returned resources in the response body. Must be in the format PARAMETER.ORDER, where PARAMETER is any allowed query parameter in the request (e.g. id) and ORDER is one of the following:

  • asc - sort by the parameter in ascending order
  • desc - sort by the parameter in descending order
limitinteger

The maximum number of resources to return. Up to a maximum of 100 resources can be returned in a request. Not including this parameter will default to returning all available resources selected up to maximum 100.

offsetinteger

Starting index for resources returned based on the provided query parameters and sorting conditions. Not including this parameter will default to starting with the first resource (inclusive).

Headers

api-tokenstring required

Your API access token for authentication and access to the Helcim API

Response

Successful payment plan collection query. The response body contains the data representation of all queried payment plans matching the provided parameters.

Example response

{
  "data": [
    {
      "id": 123456,
      "dateCreated": "2024-01-01 12:30:45",
      "dateUpdated": "1970-01-01 00:00:00",
      "name": "My new monthly plan",
      "description": "",
      "type": "subscription",
      "status": "active",
      "currency": "CAD",
      "cardTerminalId": 12345,
      "setupAmount": 15,
      "recurringAmount": 10.5,
      "billSetupImmediately": "first_billing",
      "billingPeriod": "monthly",
      "billingPeriodIncrements": 1,
      "dateBilling": "Sign-up",
      "termType": "forever",
      "freeTrialPeriod": 0,
      "taxType": "customer",
      "taxCalculation": "country_province",
      "termLength": 0,
      "paymentMethod": "card",
      "businessEmail": "test@myBusiness.com",
      "addOnIds": [],
      "isProrated": "no"
    }
  ]
}