Sign in

v1

latestOpenAPI 3.0.22026-08-061303782.1 MB
Subscription Plans

Create a Subscription Plan

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.

post/subscription_plans

Headers

Finix-Versionstring
Example:2022-02-01

Specify the API version of your request. For more details, see Versioning.

Content-Typestring
Example:application/json

The data type being sent in the request body must be application/json.

Request body

amountinteger required

The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).

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_intervalsinteger 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.

descriptionstring

A description of the Subscription Plan.

linked_tostring required

The ID of the Merchant 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.

nicknamestring

A human-readable name for the resource.

plan_namestring required

A human-friendly name for the Subscription Plan.

tagsTags 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)

Example request

{
  "amount": 5000,
  "billing_interval": "MONTHLY",
  "discount_phase_defaults": {
    "amount": 5000
  }
}

Response

A single Subscription Plan

idstring

The ID of the resource.

created_atstring date-time

Timestamp of when the object was created.

updated_atstring date-time

Timestamp of when the object was last updated.

application_idstring

ID of the Application the resource was created under.

linked_tostring

The ID of the Merchant 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
nicknamestring

A human-readable name for the resource.

plan_namestring

A human-friendly name for the Subscription Plan.

descriptionstring

A description of the Subscription Plan.

amountinteger

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_intervalsinteger 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.

state'ACTIVE' | 'INACTIVE'

The state of the Subscription Plan.

tagsTags 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)

Example response

{
  "billing_interval": "MONTHLY",
  "amount": 5000,
  "discount_phase_defaults": {
    "amount": 5000
  }
}