---
title: "Create subscriptions"
method: POST
path: "/subscriptions"
tags: ["Subscriptions"]
---

# Create subscriptions

`POST /subscriptions`

Create one or more subscriptions to your payment plans.

## Headers

- `api-token` string, required
- `idempotency-key` string, required

## Request body

- SubscriptionCreationReq
  - `subscriptions` BaseSubscriptionCreate[]
    - `dateActivated` string, required — The date (in YYYY-MM-DD format) on which the subscription activates. Any free trial applied to the subscription begins on this date and this date determines when the first recurring billing date occurs.
    - `paymentPlanId` integer, required — The payment plan id to which the subscription is subscribing to
    - `customerCode` string, required — The code for the customer who is subscribing to the payment plan
    - `useCustomSetupAmount` boolean — When `true`, the corresponding `setupAmount` passed in the request will be applied to the subscription, overriding the default payment plan setup amount. If not specified in the request, this value is `false` by default and the payment plan default setup amount will be applied.
    - `setupAmount` number, float — The setup amount charged on the first billing for the subscription, only if `useCustomSetupAmount` is also `true`. Otherwise, the payment plan default setup amount is charged.
    - `recurringAmount` number, float, required — The recurring amount charged each cycle for the subscription. The value can differ from the payment plan if desired.
    - `withFreeTrialPeriod` boolean — Toggle indicating whether to apply the payment plan free trial period to the subscription
    - `maxCycles` integer — The number of cycles the subscription will bill before ending. This field is only applicable and required for expiring subscriptions; it will be ignored for non-expiring subscriptions. Note expiring status is determined by the payment plan `termType` field.
    - `paymentMethod` 'card' | 'bank', required
    - `addOns` SubscriptionAddOnCreateInner[] — The add-ons linked to the payment plan to apply to the subscription
      - `addOnId` integer, required — The id of the linked plan add-on to apply to the subscription
      - `quantity` integer — The number of duplicates of the indicated add-on to apply to the target subscription. If provided the add-on must support quantity editing to apply the specified quantity.

## Response `201`

Successful subscription creation. The response body contains the data representation of all newly created  subscriptions, the first payment, and applied active add-ons. If any created subscriptions were immediately billed the returned payment will indicate whether the billing was approved or declined. Only active add-ons will be present  in the response, one time add-ons that were immediately billed will not be present.

- SubscriptionCreationRes
  - `data` BaseSubscription[]
    - `id` integer
    - `dateCreated` string, date-time
    - `dateUpdated` string, date-time
    - `dateActivated` string, date
    - `dateBilling` string, date
    - `status` string
    - `paymentPlanId` integer
    - `customerCode` string
    - `timesBilled` integer
    - `setupAmount` number, float
    - `recurringAmount` number, float
    - `freeTrialPeriod` integer
    - `maxCycles` integer
    - `hasFailedPayments` 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)