--- title: "Create a Subscription Plan" method: POST path: "/subscription_plans" tags: ["Subscription Plans"] --- # Create a Subscription Plan `POST /subscription_plans` Create a `Subscription Plan` resource to group and manage recurring payments for individual `Subscription` resources. You can create a `Subscription Plan` with or without a trial period. ## Headers - `Finix-Version` string - `Content-Type` string ## Request body - CreateSubscriptionPlan - `amount` integer, required — The total amount that will be debited in cents (e.g. 100 cents to debit $1.00). - `billing_defaults` object, required — Object containing default billing settings. - `collection_method` 'ACH' | 'BILL_AUTOMATICALLY', required — The method by which subscription payments are collected. - `billing_interval` 'BIMONTHLY' | 'BIWEEKLY' | 'BIYEARLY' | 'DAILY' | 'MONTHLY' | 'QUARTERLY' | 'SEMIYEARLY' | 'TRIYEARLY' | 'WEEKLY' | 'YEARLY', required — How often the buyer is billed. The possible billing intervals are as follows: - `BIMONTHLY`: every 2 months - `BIWEEKLY`: every 2 weeks - `BIYEARLY`: every 2 years - `DAILY`: every day - `MONTHLY`: every month - `QUARTERLY`: each quarter - `SEMIYEARLY`: twice a year - `TRIYEARLY`: every 3 years - `WEEKLY`: every week - `YEARLY`: every year - `currency` 'USD', required — ISO 4217 3-letter currency code. Currently, the only `currency` supported is `USD`. - `default_total_billing_intervals` integer, nullable — The total number of billing intervals for subscriptions created from this plan. This is the count of recurring billing cycles, with the interval unit defined by the plan’s `billing_interval`, such as weekly, monthly, etc. If included, the plan’s `duration_type` will be set to `FIXED_TERM`. Subscriptions created with this plan will use the default duration in the `total_billing_intervals` field. The subscription's `expires_at` field will be set to the datetime when the subscription expires based on the plan's `default_total_billing_intervals`. - `description` string — A description of the `Subscription Plan`. - `discount_phase_defaults` object - `amount` integer — The total amount that will be debited in cents (e.g. 100 cents to debit $1.00). - `billing_interval_count` integer — The number of billing intervals the discount applies. After this period, the subscriber is charged the full `amount` from the `Subscription`. - `linked_to` string, required — The ID of the [`Merchant`](#Merchants) resource that you wish to link to the `Subscription Plan` (i.e., the merchant that the subscription plan belongs to). At this time, only approved merchants with one of the following processors are valid: - `DUMMY_V1` - `FINIX_V1` - `linked_type` 'MERCHANT', required — The type of the resource that is specified in the `linked_to` field. - `nickname` string — A human-readable name for the resource. - `plan_name` string, required — A human-friendly name for the `Subscription Plan`. - `tags` Tags, nullable — Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`) - `trial_defaults` object — Object containing default trial settings. - `interval_count` integer, required — The number of intervals of `interval_type` used to describe the duration of the trial. - `interval_type` 'DAY' | 'MONTH' | 'WEEK' | 'YEAR', required — The unit of time for the trial period. ## Response `201` A single Subscription Plan - SubscriptionPlan - `id` string — The ID of the resource. - `created_at` string, date-time — Timestamp of when the object was created. - `updated_at` string, date-time — Timestamp of when the object was last updated. - `application_id` string — ID of the `Application` the resource was created under. - `linked_to` string — The ID of the [`Merchant`](#Merchants) resource that you wish to link to the `Subscription Plan` (i.e., the merchant that the subscription plan belongs to). At this time, only approved merchants with one of the following processors are valid: - `DUMMY_V1` - `FINIX_V1` - `linked_type` 'MERCHANT' — The type of the resource that is specified in the `linked_to` field. - `billing_interval` 'BIMONTHLY' | 'BIWEEKLY' | 'BIYEARLY' | 'DAILY' | 'MONTHLY' | 'QUARTERLY' | 'SEMIYEARLY' | 'TRIYEARLY' | 'WEEKLY' | 'YEARLY' — How often the buyer is billed. The possible billing intervals are as follows: - `BIMONTHLY`: every 2 months - `BIWEEKLY`: every 2 weeks - `BIYEARLY`: every 2 years - `DAILY`: every day - `MONTHLY`: every month - `QUARTERLY`: each quarter - `SEMIYEARLY`: twice a year - `TRIYEARLY`: every 3 years - `WEEKLY`: every week - `YEARLY`: every year - `nickname` string — A human-readable name for the resource. - `plan_name` string — A human-friendly name for the `Subscription Plan`. - `description` string — A description of the `Subscription Plan`. - `amount` integer — The total amount that will be debited in cents (e.g. 100 cents to debit $1.00). - `currency` 'USD' | 'CAD' — ISO 4217 3-letter currency code. - `default_total_billing_intervals` integer, nullable — The total number of billing intervals for subscriptions created from this plan. This is the count of recurring billing cycles, with the interval unit defined by the plan’s `billing_interval`, such as weekly, monthly, etc. If included, the plan’s `duration_type` will be set to `FIXED_TERM`. Subscriptions created with this plan will use the default duration in the `total_billing_intervals` field. The subscription's `expires_at` field will be set to the datetime when the subscription expires based on the plan's `default_total_billing_intervals`. - `duration_type` 'FIXED_TERM' | 'EVERGREEN', nullable — Whether subscriptions created from this plan will have a fixed term or will continue until canceled. If `default_total_billing_intervals` is set, this plan's `duration_type` is automatically set to `FIXED_TERM`. Otherwise, the `duration_type` is set to `EVERGREEN`. - `billing_defaults` object — Object containing default billing settings. - `collection_method` 'BILL_AUTOMATICALLY' — The method by which subscription payments are collected. At this time, only `BILL_AUTOMATICALLY` is supported. - `send_invoice` boolean — This feature has yet to be implemented. - `send_receipt` boolean — This feature has yet to be implemented. - `trial_defaults` object — Object containing default trial settings. - `interval_type` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' — The unit of time for the trial period. - `interval_count` integer — The number of intervals of `interval_type` used to describe the duration of the trial. - `discount_phase_defaults` object - `amount` integer — The total amount that will be debited in cents (e.g. 100 cents to debit $1.00). - `billing_interval_count` integer — The number of billing intervals the discount applies. After this period, the subscriber is charged the full `amount`. - `state` 'ACTIVE' | 'INACTIVE' — The state of the `Subscription Plan`. - `tags` Tags, nullable — Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`) - `_links` object — An object containing link(s) relevant to the request. You can store these links for follow-up requests. - `self` Self — Link to the resource that was used in the request. - `href` string ## Other responses - `400` — Bad Request. The server cannot process the request due to malformed syntax or invalid data. - `401` — Unauthorized. Authentication is required and has failed or has not been provided. - `403` — Forbidden. The client is authenticated but does not have permission to access the resource. - `406` — Not Acceptable. The server could not accept the submitted request. Confirm how the request was formatted and submitted. --- [API](https://skmtc.net/finix/apis/finix-api-reference.md) · [All operations](https://skmtc.net/finix/apis/finix-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/finix/finix-api-reference/versions/5426f6f99c52/schema)