Subscription Billing

Finix's Subscription Billing APIs provide Platforms the option to automatically charge their Merchants on a fixed billing plan. The Subscription Billing APIs can be used to charge a Fee to a Merchant for a service, equipment, or other use case. An example of a subscription Fee is charging a Merchant a one-time registration Fee or an annual software renewal Fee.

attention

Only a User with ROLE_PLATFORM level credentials can perform these requests.

There are three steps to create and apply a Subscription to a Merchant.

Step 1: Create a Subscription Schedule

The Subscription Schedule details when the Subscription Fee is charged to the Merchant. There are two available schedule types: FIXED_TIME_INTERVAL or PERIODIC. Each schedule type provides different functionality:

The FIXED _ TIME _ INTERVAL Subscription Schedule charges a Merchant on a fixed 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.

The fixed_interval uses hourly increments. For example, to charge a Fee every day for 4 days, pass 24 in the interval field and 4 in the interval_count field in the request. There is no limit to the number of interval_count or intervals you can pass.

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

A PERIODIC_YEARLY 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, the request will error out.

A PERIODIC_MONTHLY 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 throw 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 logic also applies to leap years.

Copy

Copied

curl https://finix.sandbox-payments-api.com/subscription/subscription_schedules \
    -H "Content-Type: application/vnd.json+api" \
    -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" \
    -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" \
    -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)