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.

Request
header Parameters
Finix-Version
string
Default: 2018-01-01

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

Example: 2022-02-01
Request Body schema: application/json
amount
required
integer <int64>

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

currency
required
string

ISO 4217 3-letter currency code. Currently, the only currency supported is USD.

Value: "USD"
plan_name
required
string

A human-friendly name for the Subscription Plan.

description
string

A description of the Subscription Plan.

linked_to
required
string

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
required
string

The type of the resource that is specified in the linked_to field.

Value: "MERCHANT"
nickname
string

A human-readable name for the resource.

billing_interval
required
string

How often the customer subscriber is billed.

Enum: "DAILY" "WEEKLY" "MONTHLY" "QUARTERLY" "YEARLY"
required
object

Object containing default billing settings.

object

Object containing default trial settings.

Responses
201

A single Subscription Plan object.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

422

Invalid field

post/subscription_plans
Request samples 
Response samples 
application/json
{
  • "id": "subscription_plan_ciMZKcqAJQyZBgJ1krzU5",
  • "created_at": "2025-01-02T05:55:43.96Z",
  • "updated_at": "2025-01-02T05:55:43.96Z",
  • "amount": 19900,
  • "billing_defaults": {
    • "collection_method": "BILL_AUTOMATICALLY",
    • "send_invoice": false,
    • "send_receipt": false
    },
  • "billing_interval": "MONTHLY",
  • "currency": "USD",
  • "description": "A basic API portal account with the least features.",
  • "linked_to": "MU7noQ1wdgdAeAfymw2rfBMq",
  • "nickname": null,
  • "plan_name": "API portal - Basic",
  • "state": "ACTIVE",
  • "tags": { },
  • "trial_defaults": {
    • "interval_type": "DAY",
    • "interval_count": 30
    },
  • "_links": {}
}
List Subscription Plans
Retrieve a list of Subscription Plans. 


For details on how to query endpoints using the available parameters, see Query Parameters.


Request 
query Parameters
amount
integer
Filter by an amount equal to the given value.


 
 Example:  amount=100
amount.lt
integer
Filter by an amount less than.


 
 Example:  amount.lt=100
amount.lte
integer
Filter by an amount less than or equal.


 
 Example:  amount.lte=100
amount.gt
integer
Filter by an amount greater than.


 
 Example:  amount.gt=100
amount.gte
integer
Filter by an amount greater than or equal.


 
 Example:  amount.gte=100
limit
integer
The numbers of items to return.


 
 Example:  limit=10
after_cursor
string
Return every resource created after the cursor value.


 
 Example:  after_cursor=TRnasXQ5AmjsLnPMwnme7TL4
before_cursor
string
Return every resource created before the cursor value.


 
 Example:  before_cursor=TRnasXQ5AmjsLnPMwnme7TL4
header Parameters
Finix-Version
string
 Default:  2018-01-01
Specify the API version of your request. For more details, see Versioning.


 
 Example:  2022-02-01
Responses 
200
A list of Subscription Plans objects


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


422
Invalid field


get/subscription_plans
Request samples 
curl "https://finix.sandbox-payments-api.com/subscription_plans" \
  -H "Finix-Version: 2022-02-01" \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda
Response samples 
application/json
{
  • "_embedded": {
    • "subscription_plans": [
      ]
    },
  • "_links": {},
  • "page": {
    • "limit": 100,
    • "next_cursor": "subscription_plan_ciLn19pSKDTFoehtH7ETg"
    }
}
Fetch a Subscription Plan
Retrieve the details of a previously created Subscription Plan.


Request 
path Parameters
subscription_plan_id
required
string
The ID of the Subscription Plan.


 
header Parameters
Finix-Version
string
 Default:  2018-01-01
Specify the API version of your request. For more details, see Versioning.


 
 Example:  2022-02-01
Responses 
200
A single Subscription Plan object.


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


422
Invalid field


get/subscription_plans/{subscription_plan_id}
Request samples 
curl "https://finix.sandbox-payments-api.com/subscription_plans/subscription_plan_ciLn19pSKDTFoehtH7ETg" \
  -H "Finix-Version: 2022-02-01" \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda
Response samples 
application/json
{
  • "id": "subscription_plan_ciMZKcqAJQyZBgJ1krzU5",
  • "created_at": "2025-01-02T05:55:43.96Z",
  • "updated_at": "2025-01-02T05:55:43.96Z",
  • "amount": 19900,
  • "billing_defaults": {
    • "collection_method": "BILL_AUTOMATICALLY",
    • "send_invoice": false,
    • "send_receipt": false
    },
  • "billing_interval": "MONTHLY",
  • "currency": "USD",
  • "description": "A basic API portal account with the least features.",
  • "linked_to": "MU7noQ1wdgdAeAfymw2rfBMq",
  • "nickname": null,
  • "plan_name": "API portal - Basic",
  • "state": "ACTIVE",
  • "tags": { },
  • "trial_defaults": {
    • "interval_type": "DAY",
    • "interval_count": 30
    },
  • "_links": {}
}
Update a Subscription Plan
Update an existing Subscription Plan.


Options:


    

  • Set update_existing_subscriptions to true to update existing subscriptions.
    • 

  • Archive the Subscription Plan by setting its state to INACTIVE.
    • 



Request 
path Parameters
subscription_plan_id
required
string
The ID of the Subscription Plan.


 
header Parameters
Finix-Version
string
 Default:  2018-01-01
Specify the API version of your request. For more details, see Versioning.


 
 Example:  2022-02-01
Request Body schema: application/json
amount
integer <int64> 
The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).


 
nickname
string
A human-readable name for the resource.


 
description
string
A description for the Subscription Plan.


 
state
string
The state of the Subscription Plan.


 Enum: "ACTIVE" "INACTIVE"  
update_existing_subscriptions
boolean
Set to true to update existing subscriptions created from this plan or false to make updates only effective for future subscriptions created from this plan. The default is false.


 
Responses 
200
A single Subscription Plan object.


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


422
Invalid field


put/subscription_plans/{subscription_plan_id}
Request samples 
Response samples 
application/json
{
  • "id": "subscription_plan_ciLn19pSKDTFoehtH7ETg",
  • "created_at": "2025-01-01T09:13:18.70Z",
  • "updated_at": "2025-01-02T06:01:31.41Z",
  • "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N",
  • "linked_type": "MERCHANT",
  • "billing_interval": "MONTHLY",
  • "nickname": "API portal - Basic plan",
  • "plan_name": "API portal - Basic",
  • "description": "A starter plan with minimal features",
  • "amount": 19900,
  • "currency": "USD",
  • "billing_defaults": {
    • "collection_method": "BILL_AUTOMATICALLY",
    • "send_invoice": false,
    • "send_receipt": false
    },
  • "trial_defaults": null,
  • "state": "ACTIVE",
  • "tags": { },
  • "_links": {}
}