Subscription Billing

With Subscription Billing, Platforms can automatically charge their Merchants on a fixed billing plan. Subscription Billing can be used to charge a Fee to a Merchant for a service, good, or any other use case.

You can create Subscriptions to charge your Merchants using the Finix Dashboard or the Finix API.

Finix API

Using Finix's API, there are three steps to create a fixed billing plan (called a Subscription in Finix) and apply it to a Merchant.

attention

The Subscription Billing APIs are only available for Finix Core customers. If you have additional questions, please reach out to your Finix point of contact.

Step 1: Create a Subscription Schedule

The Subscription Schedule details when the Subscription Fee is charged to the Merchant. When creating a subscription_schedule, there are two schedules available forsubscription_type:

FIXED_TIME_INTERVAL

The FIXED_TIME_INTERVAL Subscription Schedule charges a Merchant on a fixed hourly interval. For example, if a Merchant purchases a POS for $100, you can set a FIXED_TIME_INTERVAL schedule to charge the Merchant $25 four times until the $100 is paid.

To charge a Fee every day for 4 days, pass 24 in the hourly_interval field and 4 in the interval_count field. There is no limit to the number of intervals you can include in interval_count.

PERIODIC

The PERIODIC Subscription Schedule charges a Merchant on a specific day. Examples include a monthly software Fee or an annual PCI compliance Fee to be charged monthly or annually. There are two PERIODIC Subscription Schedules you can charge:

  • PERIODIC_YEARLY : The Subscription Schedule charges a Merchant a Fee once a year on a specific day and month. If you pass in a day that does not exist, such as 2/31 or 11/30 in the day field, an error will return.
  • PERIODIC_MONTHLY : The Subscription Schedule charges a Merchant a Fee once a month on a specific day. The month field should not be passed in the payload, or the request will return an error.
    • If you pass in 31 to represent the last day of a month, for every month that does not have 31 days, the Fee will be charged on the last day of the month. For example, Fees for February would be charged on the 28th, September on the 30th, and etc. This also applies to leap years.
Copy
Copied
curl https://finix.sandbox-payments-api.com/subscription/subscription_schedules \
    -H "Content-Type: application/vnd.json+api" \
    -H 'Finix-Version:2022-02-01' \
    -u  UStxEci4vXxGDWLQhNvao7YY:25038781-2369-4113-8187-34780e91052e \
    -d '
	{
	    "line_item_type": "FEE",
	    "nickname": "Fixed_Time_Subscription_Schedule",
	    "fixed_time_interval_offset": {
	        "interval_count": 4,
	        "hourly_interval": 24
	    },
	    "subscription_type": "FIXED_TIME_INTERVAL"
	}'

Example Response:

Copy
Copied
{
  "id" : "SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ",
  "created_at" : "2022-01-27T07:44:05.40Z",
  "updated_at" : "2022-01-27T07:44:05.40Z",
  "created_by" : "UStxEci4vXxGDWLQhNvao7YY",
  "fixed_time_interval_offset" : {
    "hourly_interval" : 24,
    "interval_count" : 4
  },
  "line_item_type" : "FEE",
  "nickname" : "Fixed_Time_Subscription_Schedule",
  "period_offset" : null,
  "subscription_type" : "FIXED_TIME_INTERVAL",
  "tags" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ"
    },
    "amounts" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ/subscription_amounts"
    }
  }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/subscription/subscription_schedules

Fixed-time Interval Offset Request Arguments

Field Type Description
hourly_interval integer, required Hourly increments between recurring charges
interval_count integer, required Number of recurring charges

Request Arguments

Field Type Description
line_item_type string, required Subscription Schedule type. For subscriptions, the type is FEE
nickname string, required Subscription Schedule name
subscription_type string, required Subscription Schedule type. Available types are: PERIODIC_MONTHLY, PERIODIC_YEARLY or FIXED_TIME_INTERVAL
tags object, optional Key value pair for annotating custom metadata (e.g. order numbers)

Response

Field Type Description
id string ID of the Subscription Schedule
created_at string Timestamp of when the Subscription Schedule was created
updated_at string Timestamp of when the Subscription Schedule was last updated
created_by string User ID
fixed_time_offset object Specifies when the Fee is charged
hourly_interval integer Hourly increments between recurring charges
interval_count integer Number of recurring charges
line_item_type string Subscription Schedule type. For subscriptions, the type is FEE
nickname string Subscription Schedule name
period_offset object Specifies when the Fee is charged. This field is null for FIXED_TIME_INTERVAL Subscription Schedules
subscription_type string Subscription Schedule type
tags object Key value pair for annotating custom metadata (e.g. order numbers)

Step 2: Create a Subscription Amount

The next step is to create and associate a Subscription Amount to a Subscription Schedule. The Subscription Amount is the amount to be charged to a Merchant. To associate a Subscription Amount with a Subscription Schedule pass FEE in the amount_type field of the request. You can associate up to 25 amounts to a schedule. To add an additional Subscription Amount to a schedule, make a new Subscription Amount request with the Subscription Schedule ID.

If you add another Subscription Amount to a schedule, all Merchants enrolled in that schedule will be charged the additional amount when the enrollment is triggered. For example, if your schedule charges a monthly software license fee of $10, and you add another monthly $10 reporting fee, all Merchants enrolled in this schedule will be charged $20 per month once the enrollment is triggered.

Copy
Copied
curl https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ/subscription_amounts  \
    -H "Content-Type: application/vnd.json+api" \
    -H 'Finix-Version:2022-02-01' \
    -u  UStxEci4vXxGDWLQhNvao7YY:25038781-2369-4113-8187-34780e91052e \
    -d '
	{
	    "amount_type": "FEE",
	    "fee_amount_data": {
	        "currency": "USD",
	        "amount": 2500,
	        "label": "POS_INSTALLMENT_FEE"
	    },
	    "nickname": "POS_INSTALLMENT_FEE",
	    "tags": {
	        "order_number": "124"
	    }
	}'

Example Response:

Copy
Copied
{
  "id" : "SUBAMOUNT_uKg6g5SL5mbAUcbt7PkDDq",
  "created_at" : "2022-01-27T07:44:08.16Z",
  "updated_at" : "2022-01-27T07:44:08.16Z",
  "amount_type" : "FEE",
  "created_by" : "UStxEci4vXxGDWLQhNvao7YY",
  "fee_amount_data" : {
    "amount" : 2500,
    "currency" : "USD",
    "label" : "POS_INSTALLMENT_FEE"
  },
  "nickname" : "POS_INSTALLMENT_FEE",
  "subscription_schedule" : "SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ",
  "tags" : {
    "order_number" : "124"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ/subscription_amounts/SUBAMOUNT_uKg6g5SL5mbAUcbt7PkDDq"
    },
    "schedule" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ"
    }
  }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/subscription/subscription_schedules/:SUBSCRIPTION_SCHEDULE_ID/subscription_amounts

URL Parameters

Parameter Description
:SUBSCRIPTION_SCHEDULE_ID ID of the Subscription Schedule

Request Arguments

Field Type Description
amount_type string, required Subscription Amount type. For subscriptions, the type is FEE
fee_amount_data object, required Key value pair specifying amount and currency
nickname string, required Subscription Amount name
tags object, optional Key value pair for annotating custom metadata (e.g. order numbers)

Fee Amount Object Request Arguments

Field Type Description
amount integer, required A positive integer in cents representing how much to charge on a recurring basis
currency string, required Three-letter ISO currency code in uppercase
label string, optional The display name of the Settlement that can be used for filtering purposes

Response

Field Type Description
id string ID of the Subscription Amount
created_at string Timestamp of when the Subscription Amount was created
updated_at string Timestamp of when the Subscription Amount was last updated
amount_type string Subscription Amount type. For subscriptions, the type is FEE
created_by string User ID
fee_amount_data object Key value pair specifying amount and currency
amount integer A positive integer in cents representing how much to charge on a recurring basis
currency string Three-letter ISO currency code in uppercase
label string The display name of the Settlement that can be used for filtering purposes
nickname string Subscription Amount name
subscription_schedule string ID of the Subscription Schedule
tags object Key value pair for annotating custom metadata (e.g. order numbers)

Step 3: Create a Subscription Enrollment and Enroll the Merchant

A Subscription Enrollment details which Merchant gets charged, to what schedule, and when the subscription will start. The Subscription Enrollment must be associated with a Subscription Schedule.

Copy
Copied
curl https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ/subscription_enrollments \
    -H "Content-Type: application/vnd.json+api" \
    -H 'Finix-Version:2022-02-01' \
    -u  UStxEci4vXxGDWLQhNvao7YY:25038781-2369-4113-8187-34780e91052e \
    -d '
	{
	    "merchant": "MUucec6fHeaWo3VHYoSkUySM",
	    "started_at": "2022-11-11T16:50:59.891Z",
	    "nickname": "Security Fee",
	    "tags": {
	        "enrollment_info": "Security Fee Enrollment"
	    }
	}'

Example Response:

Copy
Copied
{
  "id" : "SUBENROLLMENT_uPamF4YuEyzVTT42hwYgBV",
  "created_at" : "2022-01-27T07:44:09.08Z",
  "updated_at" : "2022-01-27T07:44:09.08Z",
  "created_by" : "UStxEci4vXxGDWLQhNvao7YY",
  "ended_at" : null,
  "merchant" : "MUucec6fHeaWo3VHYoSkUySM",
  "nickname" : "Security Fee",
  "started_at" : "2022-11-11T16:50:59.89Z",
  "subscription_schedule" : "SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ",
  "tags" : {
    "enrollment_info" : "Security Fee Enrollment"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_enrollments/SUBENROLLMENT_uPamF4YuEyzVTT42hwYgBV"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUucec6fHeaWo3VHYoSkUySM"
    },
    "schedule" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ"
    },
    "amounts" : {
      "href" : "https://finix.sandbox-payments-api.com/subscription/subscription_schedules/SUBSCHEDULE_uxsUJrgbQZEXsWm9toq6gZ/subscription_amounts"
    }
  }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/subscription/subscription_schedules/:SUBSCRIPTION_SCHEDULE_ID/subscription_enrollments

URL Parameters

Parameter Description
:SUBSCRIPTION_SCHEDULE_ID ID of the Subscription Schedule

Request Arguments

Field Type Description
ended_at string, optional When the subscription will end in DateTime format. This field can be null. If left null, the Fee will continue in perpetuity
merchant string, required ID of the Merchant
nickname string, required Subscription Enrollment name
started_at string, required When the subscription will begin in DateTime format. The start date must be a future date
tags object, optional Key value pair annotating custom metadata (e.g. order numbers)

Response

Field Type Description
id string Subscription Enrollment ID
created_at string Timestamp of when the Subscription Enrollment was created
updated_at string Timestamp of when the Subscription Enrollment was last updated
created_by string User ID
ended_at string When the subscription will end in DateTime format. If left blank, it will continue in perpetuity
merchant string ID of the Merchant
nickname string Name of the Subscription Enrollment
started_at string When the subscription will begin in DateTime format
subscription_schedule string ID of the Subscription Schedule
tags object Key value pair annotating custom metadata (e.g. order numbers)