# Subscriptions Quickstart

Learn how to create subscriptions quickly using the Finix Dashboard or using the Finix API.

Subscriptions allow you to charge a fixed amount to card or bank account on a recurring time period. You can use Subscriptions to charge buyers, customers, and more.

Example use cases for Subscriptions:

- Charging buyers a recurring monthly fee to access a gym or health club
- Charging buyers an annual membership fee for services or goods rendered
- Charging merchants a monthly or annual fee for using your software


Pricing
This product requires an additional fee. Please get in touch with your Finix Point of Contact for pricing on this feature.

## Creating a Subscription on the Finix Dashboard

You can create a `Subscription` in the Finix Dashboard without any development work. Using the Finix Dashboard, you can:

- Create subscriptions from existing buyers and payment instruments
- View the existing `Subscriptions`
- Cancel a `Subscription` if a buyer or customer chooses to end their goods or services


### Step 1: Navigate to Subscriptions

To create a Subscription in the Finix Dashboard:

1. Log into the [Finix Dashboard](https://finix.payments-dashboard.com/Login).
2. Click **Subscriptions**.


Subscriptions List Page
1. Click **Create Subscription**


Subscriptions List Page
1. Fill out the form with the requested details.


### Step 2. Create a Subscription

When you click on **Create Subscription**, a form will appear with the following options:

#### Billing settings

This section specifies how you want to bill your buyers.

- Subscription Name
- Billing Frequency
- Recurring Price


Create Subscriptions
#### Trial phase

You can enter a trial phase if your `Subscription` requires a set number of days before charging the buyer. For example, a 30-day trial, 3-month trial, or other combinations are possible.

#### Discount phase

You can enter a discount phase if you would like to have a discounted rate for a set of amount of intervals. These take place after the Trial Phase is completed.

#### Start date

You can specify a start date for the subscription in the future. This can be useful if you would like all your subscriptions to start on the same day.

#### Interval length

If you want to create a Subscription for a set amount of time, you can specify an interval length. For example, if you have a monthly subscription, you can specify an interval length of 6 and the subscription will bill for 6 months.

#### Select Buyer

When you create a Subscription, you'll need to:

1. Select a buyer you want to charge. This can be either a buyer, seller, or recipient identity.
2. Select the payment instrument you want to bill.


#### Creating a Buyer and Payment Instrument

On the **Create Subscription** page, we allow you to create a buyer and a card payment instrument.

If you would like to add a bank account on this page, you will need to use our API. If you require an exception, email our support team.

#### Review and create Subscriptions

After filling out the previous section, you can create the subscription.

Depending on whether there is a trial phase or not, the subscription will create a transfer shortly after creation. The initial transfer will be made within 60 minutes of the subscription creation.

##### Card validation with $0 Authorization

When a subscription is created using a card-type payment instrument, Finix automatically performs a **$0 `Authorization`** to validate the card. This soft check confirms that the
card is active and that the billing address and security code match the card issuer’s records (AVS and CVV checks).

By performing this check up front, Finix helps reduce failed payments and prevent fraudulent transactions — ensuring a smoother experience for both you and your customers.

## Additional details

### Supported payment methods

Subscriptions currently support:

- Recurring Card payments
- Recurring Bank account payments (ACH in USA and EFTs in Canada)


For more details about ACH payments, see [ACH Direct Debit](/guides/online-payments/bank-payments/ach-direct-debits).

### Supported time periods

Finix supports the following time periods for Subscriptions:

- Daily
- Weekly
- Monthly
- Quarterly
- Yearly


When creating a Subscription, you can specify the `billing_frequency`.

## Creating a Subscription via API

To create a Subscription, include:

- The ID of the `Merchant` that the `Subscription` will be `linked_to`
- The `amount` and `currency` of the `Subscription`
- The `subscription_details`
- The `buyer_details` including both the `identity_id` and `instrument_id`


At this time, only APPROVED Merchants with one of the following processors can create subscriptions:

- `DUMMY_V1`
- `FINIX_V1`


For detailed API information, please see our [Subscriptions API Reference](/api/subscriptions/createsubscription).

The following example shows how to create a basic subscription:

Example
API Definition
Example
Subscription

```json Subscription
{
  "id": "subscription_cxe8cii53VTHqk5Q1SqP6",
  "created_at": "2026-02-17T18:36:16.36Z",
  "updated_at": "2026-02-17T18:36:16.36Z",
  "application_id": "APc9vhYcPsRuTSpKD9KpMtPe",
  "first_charge_at": "2026-02-17T18:36:16.00Z",
  "next_billing_date": {
    "year": 2026,
    "month": 2,
    "day": 17
  },
  "amount": 19900,
  "buyer_details": {
    "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S",
    "instrument_id": "PImXAVgkKVshKWWHUk4xXbve",
    "requested_delivery_methods": [],
    "shipping_address": null
  },
  "currency": "USD",
  "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ",
  "linked_type": "MERCHANT",
  "nickname": null,
  "billing_interval": "MONTHLY",
  "subscription_details": {
    "collection_method": "BILL_AUTOMATICALLY",
    "send_invoice": false,
    "send_receipt": false,
    "trial_details": null,
    "discount_phase_details": null,
    "notification_preferences": {
      "send_confirmation": false
    }
  },
  "subscription_phase": "EVERGREEN",
  "state": "ACTIVE",
  "subscription_plan_id": null,
  "start_subscription_at": "2026-02-17T18:35:16.102Z",
  "total_billing_intervals": null,
  "expires_at": null,
  "canceled_via": null,
  "tags": {
    "order_number": "21DFASJSAKAS"
  },
  "subscription_link_id": null,
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cxe8cii53VTHqk5Q1SqP6"
    }
  }
}
```

API Definition
### Trial period

You can create a subscription with a trial period by providing `trial_details` in the request body.

For example, to include a trial period that lasts one month set `trial_details.interval_type` to `MONTH` and `trial_details.interval_count` to `1`.

After creating a `Subscription`, a `Transfer` will occur after the trial period has elapsed. The `first_charge_at` property in the response determines when the `Transfer` will occur.

Example
API Definition
Example
Subscription - Trial Period

```json Subscription - Trial Period
{
  "id": "subscription_cxe8BQxFvyPu87w2b6Hfd",
  "created_at": "2026-02-17T18:41:49.25Z",
  "updated_at": "2026-02-17T18:41:49.25Z",
  "application_id": "APc9vhYcPsRuTSpKD9KpMtPe",
  "first_charge_at": "2026-03-17T18:41:49.00Z", // [!code highlight]
  "next_billing_date": {
    "year": 2026,
    "month": 3,
    "day": 17
  },
  "amount": 19900,
  "buyer_details": {
    "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S",
    "instrument_id": "PImXAVgkKVshKWWHUk4xXbve",
    "requested_delivery_methods": [],
    "shipping_address": null
  },
  "currency": "USD",
  "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ",
  "linked_type": "MERCHANT",
  "nickname": null,
  "billing_interval": "MONTHLY",
  "subscription_details": {
    "collection_method": "BILL_AUTOMATICALLY",
    "send_invoice": false,
    "send_receipt": false,
    "trial_details": {
      "interval_type": "MONTH",
      "interval_count": 1,
      "trial_started_at": "2026-02-17T18:40:48.98Z",
      "trial_expected_start_at": "2026-02-17T18:40:48.98Z",
      "trial_expected_end_at": "2026-03-20T05:09:54.98Z"
    },
    "discount_phase_details": null,
    "notification_preferences": {
      "send_confirmation": false
    }
  },
  "subscription_phase": "TRIAL", // [!code highlight]
  "state": "ACTIVE",
  "subscription_plan_id": null,
  "start_subscription_at": "2026-02-17T18:40:48.984Z",
  "total_billing_intervals": null,
  "expires_at": null,
  "canceled_via": null,
  "tags": {},
  "subscription_link_id": null,
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cxe8BQxFvyPu87w2b6Hfd"
    }
  }
}
```

API Definition
### Discount period

To apply a discount period, include `discount_phase_details` in the request body.

For example, if the full subscription price is $20 per month, and you want to offer a discounted rate of $10 per month for three months, set `discount_phase_details.amount` to `1000` and `discount_phase_details.billing_interval_count` to `3`.

After this discount period, the subscriber will be charged the full `amount` of the `Subscription`.

Example
API Definition
Example
Subscription - Discount Phase

```json Subscription - Discount Phase
{
  "id": "subscription_cxe8oDnBbKKDGMQQaWZca",
  "created_at": "2026-02-17T18:38:50.28Z",
  "updated_at": "2026-02-17T18:38:50.28Z",
  "application_id": "APc9vhYcPsRuTSpKD9KpMtPe",
  "first_charge_at": "2026-02-17T18:38:50.00Z",
  "next_billing_date": {
    "year": 2026,
    "month": 2,
    "day": 17
  },
  "amount": 2000,
  "buyer_details": {
    "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S",
    "instrument_id": "PImXAVgkKVshKWWHUk4xXbve",
    "requested_delivery_methods": [],
    "shipping_address": null
  },
  "currency": "USD",
  "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ",
  "linked_type": "MERCHANT",
  "nickname": "Finflix Gold Package",
  "billing_interval": "MONTHLY",
  "subscription_details": {
    "collection_method": "BILL_AUTOMATICALLY",
    "send_invoice": false,
    "send_receipt": false,
    "trial_details": null,
    "discount_phase_details": {
      "amount": 1000,
      "billing_interval_count": 3,
      "discount_phase_started_at": "2026-02-17T18:37:50.01Z",
      "discount_phase_expected_start_at": "2026-02-17T18:37:50.01Z",
      "discount_phase_expected_end_at": "2026-05-17T18:37:50.01Z"
    },
    "notification_preferences": {
      "send_confirmation": false
    }
  },
  "subscription_phase": "DISCOUNT", // [!code highlight]
  "state": "ACTIVE",
  "subscription_plan_id": null,
  "start_subscription_at": "2026-02-17T18:37:50.010Z",
  "total_billing_intervals": null,
  "expires_at": null,
  "canceled_via": null,
  "tags": {},
  "subscription_link_id": null,
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cxe8oDnBbKKDGMQQaWZca"
    }
  }
}
```

API Definition
### Start date

Finix allows you to specify a start date for subscriptions. The `start_subscription_at` field takes an ISO8601 formatted timestamp to start the subscription. The timestamp must be in the future.

Example
API Definition
Example
Subscription - Future Start Date

```json Subscription - Future Start Date
{
  "id": "subscription_czjv1q7i5sjG4q61tDVz8",
  "created_at": "2026-04-22T21:14:12.33Z",
  "updated_at": "2026-04-22T21:14:12.33Z",
  "amount": 10000,
  "application_id": "APc9vhYcPsRuTSpKD9KpMtPe",
  "billing_interval": "MONTHLY",
  "buyer_details": {
    "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S",
    "instrument_id": "PImXAVgkKVshKWWHUk4xXbve",
    "requested_delivery_methods": [],
    "shipping_address": null
  },
  "canceled_via": null,
  "currency": "USD",
  "expires_at": null,
  "first_charge_at": "2026-08-15T22:42:05.49Z",
  "has_usage_based_plan": false,
  "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ",
  "linked_type": "MERCHANT",
  "next_billing_date": {
    "year": 2026,
    "month": 8,
    "day": 15
  },
  "nickname": "Monthly Cheese Delivery Club",
  "start_subscription_at": "2026-08-15T22:42:05.490Z", // [!code highlight]
  "state": "NOT_STARTED",
  "subscription_details": {
    "collection_method": "BILL_AUTOMATICALLY",
    "send_invoice": false,
    "send_receipt": false,
    "trial_details": null,
    "discount_phase_details": null,
    "notification_preferences": {
      "send_confirmation": false
    }
  },
  "subscription_link_id": null,
  "subscription_phase": "NONE",
  "subscription_plan_id": null,
  "tags": {},
  "total_billing_intervals": null,
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_czjv1q7i5sjG4q61tDVz8"
    }
  }
}
```

API Definition
### Billing cycle day

By default, a subscription bills on the day the subscription starts. For example, a monthly subscription that starts on March 15 bills on the 15th of every month.

To bill on a different day of the month, include `billing_cycle_day` in the request body. This field sets the day of the month the buyer is charged, no matter what day the subscription starts. The value must be a whole number between 1 and 31.

You can set a billing cycle day for the following `billing_interval` values:

- `MONTHLY`
- `BIMONTHLY`
- `QUARTERLY`
- `SEMIYEARLY`
- `YEARLY`
- `BIYEARLY`
- `TRIYEARLY`


`DAILY`, `WEEKLY`, and `BIWEEKLY` subscriptions do not support a billing cycle day.

#### End of month handling

If a month does not include the day you selected, Finix charges the buyer on the last day of that month instead. For example, a subscription with a `billing_cycle_day` of `31` bills on April 30, then on May 31.

#### Proration period

If a subscription starts on a day that does not match the `billing_cycle_day`, Finix prorates the first invoice so the buyer only pays for the days between the start date and the first billing cycle day. This partial period is called the **proration period**. After the proration period, the buyer is charged the full amount on the billing cycle day.

##### Example 1 - Proration period

A monthly subscription is created on **March 15** with a `billing_cycle_day` of `1`:

- The buyer is charged a prorated amount for the proration period, March 15 to April 1.
- Starting April 1, the buyer is charged the full amount on the 1st of every month.


Proration period for a subscription created on March 15 with a billing cycle day of 1
##### Example 2 - Proration period with 7-day free trial

The same subscription with a 7-day free trial added:

- The trial runs from March 15 to March 22.
- The buyer is charged a prorated amount for the proration period, March 22 to April 1.
- Starting April 1, the buyer is charged the full amount on the 1st of every month.


Proration period for a subscription created on March 15 with a 7-day trial
#### Proration formula

Finix calculates the prorated amount as follows:

`prorated amount` = (`days in proration period` / `days in month`) × `amount of period`

To visualize this, the following examples all use a subscription created on **March 15**:

| Subscription Created | `billing_cycle_day` | Proration Period | Billing Starts | Days in Month |
|  --- | --- | --- | --- | --- |
| March 15 | `1` | 17 days (March 15 to April 1) | April 1 | 31 days (March 1 to April 1) |
| March 15 | `20` | 5 days (March 15 to March 20) | March 20 | 28 days (February 20 to March 20) |
| March 15 | `31` | 16 days (March 15 to March 31) | March 31 | 31 days (February 28 to March 31) |


In the last row, one month before March 31 would be February 31. That date does not exist, so Finix uses the last day of February instead.

As a full example: a $20.00 monthly subscription created on March 15 with a `billing_cycle_day` of `1` results in a prorated first charge of (17 / 31) × $20.00 = $10.97.

#### Updating the billing cycle day

You can change the `billing_cycle_day` of an existing subscription. When you do:

- Invoices that have already been issued do not change.
- The current billing period still completes at the full amount.
- On the next billing date, the buyer is charged a prorated amount that bridges the gap from the old billing cycle day to the new one. Full billing then resumes on the new billing cycle day.


For example, a monthly subscription is created on March 15, and the buyer is charged the full amount for March 15 to April 15. On April 12, you change the `billing_cycle_day` to `1`:

1. On April 15 (the next billing date), the buyer is charged a prorated amount covering April 15 to May 1.
2. Starting May 1, the buyer is charged the full amount on the 1st of every month.


Update Billing Cycle Day
API Request Example:


```shell

curl -i -X PUT \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/subscriptions \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "billing_cycle_day": 1
  }'
```

API Response:


```json
{
  "id": "subscription_cAcHtdprA5N9Nw6nKfWbt",
  "created_at": "2026-05-19T22:27:55.83Z",
  "updated_at": "2026-05-19T22:27:55.83Z",
  "amount": 19900,
  "application_id": "AP1",
  "billing_cycle_day": 21,
  "billing_interval": "MONTHLY",
  "buyer_details": {
    "identity_id": "IDe8MHoq9cevVGocJwpAN8tR",
    "instrument_id": "PIh5syYGDw2SnvFjPVLcV3oD",
    "requested_delivery_methods": [],
    "shipping_address": null
  },
  "canceled_via": null,
  "currency": "USD",
  "expires_at": null,
  "first_charge_at": "2026-05-20T22:26:55.576Z",
  "has_usage_based_plan": false,
  "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N",
  "linked_type": "MERCHANT",
  "next_billing_date": {
    "year": 2026,
    "month": 5,
    "day": 20
  },
  "nickname": "Michael Gym Membership - Gold Gym #22919132",
  "start_subscription_at": "2026-05-20T22:26:55.576Z",
  "state": "ACTIVE",
  "subscription_details": {
    "collection_method": "BILL_AUTOMATICALLY",
    "send_invoice": false,
    "send_receipt": false,
    "trial_details": null,
    "discount_phase_details": null,
    "notification_preferences": {
      "send_confirmation": false
    }
  },
  "subscription_link_id": null,
  "subscription_phase": "EVERGREEN",
  "subscription_plan_id": null,
  "tags": {
    "key1": "value1",
    "key2": "value2"
  },
  "total_billing_intervals": null,
  "_links": {
    "self": {
      "href": "http://localhost/subscriptions/subscription_cAcHtdprA5N9Nw6nKfWbt"
    }
  }
}
```

### Fixed length Subscriptions

To create fixed-length subscriptions, you can pass `total_billing_intervals` in the request body. The API will return an `expires_at` field to let you know when the `Subscription` will expire. The `subscription_phase` will also return a value of `FIXED`.

Example
API Definition
Example
Subscription - Fixed-Length

```json Subscription - Fixed-Length
{
  "id": "subscription_cxe8rTTPCwzUu7p1zmk6t",
  "created_at": "2026-02-17T18:39:34.38Z",
  "updated_at": "2026-02-17T18:39:34.38Z",
  "application_id": "APc9vhYcPsRuTSpKD9KpMtPe",
  "first_charge_at": "2026-02-17T18:39:33.00Z",
  "next_billing_date": {
    "year": 2026,
    "month": 2,
    "day": 17
  },
  "amount": 19900,
  "buyer_details": {
    "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S",
    "instrument_id": "PImXAVgkKVshKWWHUk4xXbve",
    "requested_delivery_methods": [],
    "shipping_address": null
  },
  "currency": "USD",
  "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ",
  "linked_type": "MERCHANT",
  "nickname": null,
  "billing_interval": "MONTHLY",
  "subscription_details": {
    "collection_method": "BILL_AUTOMATICALLY",
    "send_invoice": false,
    "send_receipt": false,
    "trial_details": null,
    "discount_phase_details": null,
    "notification_preferences": {
      "send_confirmation": false
    }
  },
  "subscription_phase": "FIXED", // [!code highlight]
  "state": "ACTIVE",
  "subscription_plan_id": null,
  "start_subscription_at": "2026-02-17T18:38:33.747Z",
  "total_billing_intervals": 12,
  "expires_at": "2027-02-17T18:38:33.747Z", // [!code highlight]
  "canceled_via": null,
  "tags": {},
  "subscription_link_id": null,
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cxe8rTTPCwzUu7p1zmk6t"
    }
  }
}
```

API Definition