---
title: "Create payment plans"
method: POST
path: "/payment-plans"
tags: ["Payment Plans"]
---

# Create payment plans

`POST /payment-plans`

Create one or more payment plans customers can subscribe to.

## Headers

- `api-token` string, required

## Request body

- PaymentPlanCreationReq
  - `paymentPlans` BasePaymentPlanCreate[]
    - `name` string, required — The new payment plan name. All plans must have a name between 3 and 100 characters in length.
    - `description` string — Additional information describing the new payment plan.
    - `type` 'subscription' | 'cycle', required
    - `status` 'active' | 'inactive'
    - `cardTerminalId` integer — The card terminal that will process card transactions for subscriptions to the payment plan. Not providing a terminal will have the plan use your business' default card terminal.
    - `setupAmount` number, float — The initial monetary amount charged for new subscriptions to the payment plan. Can be charged immediately or with the first recurring billing.
    - `recurringAmount` number, float, required — The recurring monetary amount charged for subscriptions to the payment plan. Note a plan can have a recurring amount of zero, however all subscriptions to the plan must then individually specify their charged recurring amount.
    - `billSetupImmediately` 'first_billing' | 'immediate'
    - `billingPeriod` 'daily' | 'weekly' | 'monthly' | 'yearly', required
    - `billingPeriodIncrements` integer, required — 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.
    - `dateBilling` string, required — 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', required
    - `freeTrialPeriod` integer — The free trial length (in days) subscriptions to the payment plan can have
    - `taxType` 'no_tax' | 'customer' | 'merchant'
    - `taxCalculation` 'country_only' | 'country_province' | 'province_only'
    - `termLength` integer — The maximum number of cycles expiring subscriptions to this payment plan can bill for. Note this value only provides a default; subscriptions can separately define a maximum cycle length if desired. Defining this value requires the payment plan's `termType` to to be `expires`.
    - `paymentMethod` 'card' | 'bank' | 'card_bank', required
    - `addOnIds` integer[] — List of add-ons to link to this payment plan and allow subscriptions to apply
    - `emailSettingRecurringQueue` string — Whether recurring queue emails are sent to the merchant. Not including this setting will default to not sending emails. * `off` - Setting value for no emails * `merchant` - Setting value to send recurring queue emails to the merchant
    - `businessEmail` string — Merchant email used for subscriptions emails. Must not be empty if emailSettingRecurringQueue is `merchant`.
    - `isProrated` string — Identifies whether or not a payment plan is prorated. Subscriptions to prorated plans will charge a prorated first payment on the activation date or after the free trial period has ended. Note that prorated amounts include the recurring amount and recurring add-ons amount. Setup amounts and one-time add-ons are not prorated. Defining this value requires the the payment plan's `type` to be `cycle`. * `yes` - Payment plan is prorated * `no` - Payment plan will not be prorated

## Response `201`

Successful payment plan creation. The response body contains the data representation of all newly created  payment plans.

- PaymentPlanCollectionRes
  - `data` BasePaymentPlan[]
    - `id` integer
    - `dateCreated` string
    - `dateUpdated` string
    - `name` string
    - `description` string
    - `type` string
    - `status` string
    - `currency` string
    - `cardTerminalId` number, float
    - `setupAmount` number, float
    - `recurringAmount` number, float
    - `billSetupImmediately` string
    - `billingPeriod` string
    - `billingPeriodIncrements` integer
    - `dateBilling` string
    - `termType` string
    - `freeTrialPeriod` integer
    - `taxType` string
    - `taxCalculation` string
    - `termLength` integer
    - `paymentMethod` string
    - `businessEmail` string
    - `addOnIds` integer[]

## Other responses

- `400` — You are initiating a request with invalid parameter and/or body values.
- `401` — You are not authorized to access this resource. Please ensure that you are authenticated, and that you are using the `api-token` header
- `403` — You do not have permission to access this resource. Please ensure you are both authenticated and that you have the required roles/permissions active.
- `500` — Helcim internal server error encountered.

---

[API](https://skmtc.net/helcim/apis/the-helcim-api.md) · [All operations](https://skmtc.net/helcim/apis/the-helcim-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/helcim/the-helcim-api/versions/345052ca6578/schema)