# Subscription Plans

Learn how to create Subscription Plans to manage Subscriptions at scale.

Subscription plans are templates with set recurring costs and frequencies that can be used to create subscriptions for individual buyers.

Example use cases for Subscription Plans:

- You have pricing tiers (e.g., Basic, Premium, Deluxe, Enterprise). You can use the pricing tiers to group subscriptions under them.
- You have different products or services you offer that have different recurring costs and frequencies (e.g. 30 min guitar lessons, 60 min guitar lessons,)
- You charge different recurring rates based on the location


## Creating a Subscription plan on the Finix Dashboard

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

- Create `Subscription Plans`
- View all existing `Subscription Plans`
- De-Activate a `Subscription Plan` if you no longer want to add new subscriptions under that Subscription Plan.


### Step 1: Navigate to Subscription plans

To create a Subscription Plan in the Finix Dashboard:

1. Log into the [Finix Dashboard](https://finix.payments-dashboard.com/Login).
2. Click **Subscriptions** page > **Subscription Plans** tab.
3. Click **Create Subscription Plan**


1. Fill out the form with the requested details.


### Step 2. Create a Subscription plan

When you click on **Create Subscription Plan**, 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


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

#### Review and create Subscription plans

After filling out the previous section, you can create the `Subscription Plan`.

## Creating a Subscription from a Subscription plan

You have two options to create a Subscription from a Subscription Plan.

### From the Subscription plan details page

1. Navigate to a Subscription Plan
2. Click on the Actions dropdown on the top right
3. Select Create Subscription
4. Enter the buyer information and complete the form.


### From the Subscriptions list page

1. Click **Billing** → **Subscriptions**.
2. Click **Create Subscription**
3. Unselect **Create subscription without a plan**
4. Select a Subscription Plan
5. Enter the buyer information and complete the form.


## Creating a Subscription plan via API

To create a Subscription Plan, include:

- The ID of the `Merchant` that the Subscription Plan will be `linked_to`
- The `amount` and `currency` of the Subscription Plan
- Additional details of the Subscription Plan. For detailed API information, please see our [Subscriptions Plans API Reference](/api/subscription-plans/createsubscriptionplan).


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

- `DUMMY_V1`
- `FINIX_V1`


```shell Create Subscription Plan Request
curl https://finix.sandbox-payments-api.com/subscription_plans \
    -H 'Content-Type: application/json' \
    -H 'Finix-Version: 2022-02-01' \
    -u US8tzeiYEYAV1JY6SANMEXvN:67a2c4ac-9a9d-4b7f-81e2-1533d0869de0 \
    -X POST \
    -d '{
        "amount": 1099,
        "currency": "USD",
        "plan_name": "Bronze Plan",
        "description": "Test",
        "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N",
        "linked_type": "MERCHANT",
        "billing_interval": "MONTHLY",
        "billing_defaults": {
            "collection_method": "BILL_AUTOMATICALLY"
        },
        "trial_defaults": {
            "interval_type": "MONTH",
            "interval_count": "1"
        }
    }'
```

```json Create Subscription Plan Response
{
  "id": "subscription_plan_cd92Tzs8qNPbNbd2JMhN5",
  "created_at": "2024-07-13T00:28:58.42Z",
  "updated_at": "2024-07-13T00:28:58.42Z",
  "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N",
  "linked_type": "MERCHANT",
  "billing_interval": "MONTHLY",
  "nickname": null,
  "plan_name": "Bronze Plan",
  "description": "Test",
  "amount": 1099,
  "currency": "USD",
  "billing_defaults": {
    "collection_method": "BILL_AUTOMATICALLY",
    "send_invoice": false,
    "send_receipt": false
  },
  "trial_defaults": {
    "interval_type": "MONTH",
    "interval_count": 1
  },
  "state": "ACTIVE",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/subscription_plans/subscription_plan_cd92Tzs8qNPbNbd2JMhN5"
    }
  }
}
```

## Creating a Subscription from a Subscription plan via the API

To create a Subscription from a Subscription Plan, specify the `subscription_plan_id` in the request body of a `Subscription`.

Example
```shell cURL
curl -i -X POST \
  -u '<username>:<password>' \
  https://finix.sandbox-payments-api.com/subscriptions \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "buyer_details": {
      "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S",
      "instrument_id": "PImXAVgkKVshKWWHUk4xXbve"
    },
    "linked_to": "MUxdJCr9xTMnmt1vGUAqV9z4",
    "linked_type": "MERCHANT",
    "subscription_plan_id": "subscription_plan_ctBbJ1ihsC8Hpju4RQfZE"
  }'
```

API Definition
```json
{
  "$ref": "#/components/schemas/createSubscriptionFromPlan",
  "components": {
    "schemas": {
      "receipt_requested_delivery_methods": {
        "type": "array",
        "description": "A list of requested delivery methods. Each method specifies\nthe type of delivery and the destination(s) where the receipt should be sent.\n",
        "items": {
          "type": "object",
          "required": [
            "type",
            "destinations"
          ],
          "properties": {
            "type": {
              "type": "string",
              "description": "The method of receipt delivery.\n",
              "enum": [
                "EMAIL",
                "SMS",
                "PRINT"
              ]
            },
            "destinations": {
              "type": "array",
              "description": "A list of destination addresses or identifiers where the receipt should be sent.\n",
              "items": {
                "type": "string"
              },
              "minItems": 1
            }
          }
        }
      },
      "country": {
        "type": "string",
        "enum": [
          "ABW",
          "AFG",
          "AGO",
          "AIA",
          "ALA",
          "ALB",
          "AND",
          "ARE",
          "ARG",
          "ARM",
          "ASM",
          "ATA",
          "ATF",
          "ATG",
          "AUS",
          "AUT",
          "AZE",
          "BDI",
          "BEL",
          "BEN",
          "BES",
          "BFA",
          "BGD",
          "BGR",
          "BHR",
          "BHS",
          "BIH",
          "BLM",
          "BLR",
          "BLZ",
          "BMU",
          "BOL",
          "BRA",
          "BRB",
          "BRN",
          "BTN",
          "BVT",
          "BWA",
          "CAF",
          "CAN",
          "CCK",
          "CHE",
          "CHL",
          "CHN",
          "CIV",
          "CMR",
          "COD",
          "COG",
          "COK",
          "COL",
          "COM",
          "CPV",
          "CRI",
          "CUB",
          "CUW",
          "CXR",
          "CYM",
          "CYP",
          "CZE",
          "DEU",
          "DJI",
          "DMA",
          "DNK",
          "DOM",
          "DZA",
          "ECU",
          "EGY",
          "ERI",
          "ESH",
          "ESP",
          "EST",
          "ETH",
          "FIN",
          "FJI",
          "FLK",
          "FRA",
          "FRO",
          "FSM",
          "GAB",
          "GBR",
          "GEO",
          "GGY",
          "GHA",
          "GIB",
          "GIN",
          "GLP",
          "GMB",
          "GNB",
          "GNQ",
          "GRC",
          "GRD",
          "GRL",
          "GTM",
          "GUF",
          "GUM",
          "GUY",
          "HKG",
          "HMD",
          "HND",
          "HRV",
          "HTI",
          "HUN",
          "IDN",
          "IMN",
          "IND",
          "IOT",
          "IRL",
          "IRN",
          "IRQ",
          "ISL",
          "ISR",
          "ITA",
          "JAM",
          "JEY",
          "JOR",
          "JPN",
          "KAZ",
          "KEN",
          "KGZ",
          "KHM",
          "KIR",
          "KNA",
          "KOR",
          "KWT",
          "LAO",
          "LBN",
          "LBR",
          "LBY",
          "LCA",
          "LIE",
          "LKA",
          "LSO",
          "LTU",
          "LUX",
          "LVA",
          "MAC",
          "MAF",
          "MAR",
          "MCO",
          "MDA",
          "MDG",
          "MDV",
          "MEX",
          "MHL",
          "MKD",
          "MLI",
          "MLT",
          "MMR",
          "MNE",
          "MNG",
          "MNP",
          "MRT",
          "MSR",
          "MTQ",
          "MUS",
          "MWI",
          "MYS",
          "MYT",
          "NAM",
          "NCL",
          "NER",
          "NFK",
          "NGA",
          "NIC",
          "NIU",
          "NLD",
          "NOR",
          "NPL",
          "NRU",
          "NZL",
          "OMN",
          "PAK",
          "PAN",
          "PCN",
          "PER",
          "PHL",
          "PLW",
          "PNG",
          "POL",
          "PRI",
          "PRK",
          "PRT",
          "PRY",
          "PSE",
          "PYF",
          "QAT",
          "REU",
          "ROU",
          "RUS",
          "RWA",
          "SAU",
          "SDN",
          "SEN",
          "SGP",
          "SGS",
          "SHN",
          "SJM",
          "SLB",
          "SLE",
          "SLV",
          "SMR",
          "SOM",
          "SPM",
          "SRB",
          "SSD",
          "STP",
          "SUR",
          "SVK",
          "SVN",
          "SWE",
          "SWZ",
          "SXM",
          "SYC",
          "SYR",
          "TCA",
          "TCD",
          "TGO",
          "THA",
          "TJK",
          "TKL",
          "TKM",
          "TLS",
          "TON",
          "TTO",
          "TUN",
          "TUR",
          "TUV",
          "TWN",
          "TZA",
          "UGA",
          "UKR",
          "UMI",
          "URY",
          "USA",
          "UZB",
          "VAT",
          "VCT",
          "VEN",
          "VGB",
          "VIR",
          "VNM",
          "VUT",
          "WLF",
          "WSM",
          "XKX",
          "YEM",
          "ZAF",
          "ZMB",
          "ZWE"
        ],
        "nullable": true
      },
      "address": {
        "type": "object",
        "properties": {
          "line1": {
            "type": "string",
            "minLength": 1,
            "description": "First line of the address (max 35 characters).",
            "nullable": true
          },
          "line2": {
            "type": "string",
            "minLength": 1,
            "description": "Second line of the address (max 35 characters).",
            "nullable": true
          },
          "city": {
            "type": "string",
            "minLength": 1,
            "description": "City (max 20 characters).",
            "nullable": true
          },
          "region": {
            "type": "string",
            "minLength": 1,
            "description": "2-letter State code.",
            "nullable": true
          },
          "postal_code": {
            "type": "string",
            "minLength": 1,
            "description": "Zip or Postal code (max 7 characters).",
            "nullable": true
          },
          "country": {
            "$ref": "#/components/schemas/country"
          }
        },
        "required": [
          "city",
          "country",
          "line1",
          "postal_code",
          "region"
        ]
      },
      "end_subscription_at": {
        "type": "string",
        "format": "date-time",
        "nullable": true,
        "description": "Timestamp of when the subscription ends. Applies to fixed amount subscriptions only.\n\nFinix prorates the final charge if the subscription ends mid-billing-cycle. If `end_subscription_at` falls on a cycle boundary, the final charge is not prorated.\n\nThe following rules apply:\n\n- Cannot be used with `total_billing_intervals` in the same request.\n- Must be after the subscription start.\n- Must be after the free trial period.\n- Must be after the discounted phase.\n- Cannot be updated after the subscription is created.\n\n**Relationship with `total_billing_intervals` and `expires_at`:**\n\n- If `end_subscription_at` is provided, `total_billing_intervals` in the response is calculated as the number of started cycles needed to reach the end date.\n- If `total_billing_intervals` is provided, `end_subscription_at` in the response is calculated to match the last day of the final cycle.\n- Setting `end_subscription_at` also sets `expires_at` to the same value in the response.\n"
      },
      "nickname": {
        "type": "string",
        "description": "A human-readable name for the resource.",
        "nullable": true
      },
      "tags": {
        "type": "object",
        "title": "tags",
        "additionalProperties": true,
        "description": "Include up to 50 `key: value` pairs to annotate requests with custom metadata.\n- Maximum character length for individual `keys` is 40.\n- Maximum character length for individual `values` is 500.\n(For example, `order_number: 25`, `item_type: produce`, `department: sales`)",
        "nullable": true
      },
      "total_billing_intervals": {
        "type": "integer",
        "nullable": true,
        "description": "The total number of billing cycles for the `Subscription`. Cannot be used with `end_subscription_at` in the same request and cannot be updated after the subscription is created.\n\n**Relationship with `end_subscription_at`:**\n\n- If `total_billing_intervals` is provided, `end_subscription_at` in the response is calculated to match the last day of the final cycle.\n- If `end_subscription_at` is provided, `total_billing_intervals` in the response is calculated as the number of started cycles needed to reach the end date.\n",
        "example": 12
      },
      "createSubscriptionFromPlan": {
        "title": "Subscription - Subscription Plan - All Fields",
        "properties": {
          "buyer_details": {
            "type": "object",
            "description": "An object containing details about the buyer.",
            "properties": {
              "identity_id": {
                "type": "string",
                "description": "The [identity ID](/api/identities) of the buyer.",
                "example": "IDtEnKsZyJNUGK83ZTx4C45S"
              },
              "instrument_id": {
                "description": "The ID of the [`Payment Instrument`](/api/payment-instruments) from which the subscription payments get debited.",
                "example": "PImXAVgkKVshKWWHUk4xXbve"
              },
              "requested_delivery_methods": {
                "$ref": "#/components/schemas/receipt_requested_delivery_methods"
              },
              "shipping_address": {
                "$ref": "#/components/schemas/address"
              }
            },
            "required": [
              "identity_id",
              "instrument_id"
            ]
          },
          "end_subscription_at": {
            "$ref": "#/components/schemas/end_subscription_at"
          },
          "linked_to": {
            "type": "string",
            "description": "The ID of the [Merchant](/api/merchants) resource that you wish to link to the `Subscription` (i.e., the merchant that the subscription belongs to).\n\nAt this time, only approved merchants with one of the following processors are valid:\n\n- `DUMMY_V1`\n- `FINIX_V1`\n",
            "example": "MUxdJCr9xTMnmt1vGUAqV9z4"
          },
          "linked_type": {
            "type": "string",
            "description": "The type of the resource that is specified in the `linked_to` field.",
            "example": "MERCHANT",
            "enum": [
              "MERCHANT"
            ]
          },
          "nickname": {
            "$ref": "#/components/schemas/nickname"
          },
          "start_subscription_at": {
            "type": "string",
            "format": "date-time",
            "description": "Indicates that the subscription is scheduled to begin in the future. The timestamp specifies the exact start date for subscription billing.",
            "example": "2029-05-05T22:42:05.490Z"
          },
          "subscription_plan_id": {
            "type": "string",
            "description": "The ID of the `Subscription Plan` from which to create the `Subscription`.",
            "example": "subscription_plan_ctBbJ1ihsC8Hpju4RQfZE"
          },
          "tags": {
            "$ref": "#/components/schemas/tags"
          },
          "total_billing_intervals": {
            "$ref": "#/components/schemas/total_billing_intervals"
          }
        },
        "required": [
          "buyer_details",
          "linked_to",
          "linked_type",
          "subscription_plan_id"
        ]
      }
    }
  }
}
```

Example
Subscription - From Subscription Plan
```json Subscription - From Subscription Plan
{
  "id" : "subscription_cA2DeRbnuvrPQHK2HooT7",
  "created_at" : "2026-05-14T14:46:30.73Z",
  "updated_at" : "2026-05-14T14:46:30.73Z",
  "amount" : 19900,
  "application_id" : "APc9vhYcPsRuTSpKD9KpMtPe",
  "billing_interval" : "MONTHLY",
  "buyer_details" : {
    "identity_id" : "IDtEnKsZyJNUGK83ZTx4C45S",
    "instrument_id" : "PImXAVgkKVshKWWHUk4xXbve",
    "requested_delivery_methods" : [ {
      "type" : "EMAIL",
      "destinations" : [ "abc@test.com" ]
    }, {
      "type" : "SMS",
      "destinations" : [ "2348765431" ]
    } ],
    "shipping_address" : {
      "city" : "Middletown",
      "country" : "USA",
      "line1" : "324 Oak Avenue",
      "line2" : "Apartment 7",
      "postal_code" : "19734",
      "region" : "DE"
    }
  },
  "canceled_via" : null,
  "currency" : "USD",
  "expires_at" : "2028-06-01T00:00:00.000Z",
  "first_charge_at" : "2027-06-01T00:00:00.000Z",
  "has_usage_based_plan" : false,
  "linked_to" : "MUxdJCr9xTMnmt1vGUAqV9z4",
  "linked_type" : "MERCHANT",
  "next_billing_date" : {
    "year" : 2027,
    "month" : 6,
    "day" : 1
  },
  "nickname" : "Finflix Gold Package",
  "start_subscription_at" : "2027-06-01T00:00:00.000Z",
  "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" : "subscription_plan_ctBbJ1ihsC8Hpju4RQfZE", // [!code highlight]
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "total_billing_intervals" : 12,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/subscriptions/subscription_cA2DeRbnuvrPQHK2HooT7"
    }
  }
}
```

API Definition
```json
{
  "$ref": "#/components/schemas/subscription",
  "components": {
    "schemas": {
      "id": {
        "type": "string",
        "minLength": 1,
        "description": "The ID of the resource."
      },
      "created_at": {
        "type": "string",
        "format": "date-time",
        "description": "Timestamp of when the object was created."
      },
      "updated_at": {
        "type": "string",
        "format": "date-time",
        "description": "Timestamp of when the object was last updated."
      },
      "amount": {
        "type": "integer",
        "description": "The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).",
        "example": 5000,
        "format": "int64"
      },
      "billing_cycle_day": {
        "type": "integer",
        "description": "The day of the month on which the `Subscription` is billed. Only applies to subscriptions with a monthly billing cycle (e.g., `MONTHLY`, `BIMONTHLY`, `QUARTERLY`, `SEMIYEARLY`, `YEARLY`, `BIYEARLY`, `TRIYEARLY`).\n\nIf the specified day doesn't exist in a given month (e.g., April 31), the subscription is billed on the last valid day of that month.\n\nAccepted values are 1 to 31.\n",
        "minimum": 1,
        "maximum": 31,
        "example": 1,
        "nullable": true
      },
      "billing_interval": {
        "type": "string",
        "description": "How often the buyer is billed. The possible billing intervals are as follows:\n\n- `BIMONTHLY`: every 2 months\n- `BIWEEKLY`: every 2 weeks\n- `BIYEARLY`: every 2 years\n- `DAILY`: every day\n- `MONTHLY`: every month\n- `QUARTERLY`: each quarter\n- `SEMIYEARLY`: twice a year\n- `TRIYEARLY`: every 3 years\n- `WEEKLY`: every week\n- `YEARLY`: every year\n",
        "example": "MONTHLY",
        "enum": [
          "BIMONTHLY",
          "BIWEEKLY",
          "BIYEARLY",
          "DAILY",
          "MONTHLY",
          "QUARTERLY",
          "SEMIYEARLY",
          "TRIYEARLY",
          "WEEKLY",
          "YEARLY"
        ]
      },
      "receipt_requested_delivery_methods": {
        "type": "array",
        "description": "A list of requested delivery methods. Each method specifies\nthe type of delivery and the destination(s) where the receipt should be sent.\n",
        "items": {
          "type": "object",
          "required": [
            "type",
            "destinations"
          ],
          "properties": {
            "type": {
              "type": "string",
              "description": "The method of receipt delivery.\n",
              "enum": [
                "EMAIL",
                "SMS",
                "PRINT"
              ]
            },
            "destinations": {
              "type": "array",
              "description": "A list of destination addresses or identifiers where the receipt should be sent.\n",
              "items": {
                "type": "string"
              },
              "minItems": 1
            }
          }
        }
      },
      "country": {
        "type": "string",
        "enum": [
          "ABW",
          "AFG",
          "AGO",
          "AIA",
          "ALA",
          "ALB",
          "AND",
          "ARE",
          "ARG",
          "ARM",
          "ASM",
          "ATA",
          "ATF",
          "ATG",
          "AUS",
          "AUT",
          "AZE",
          "BDI",
          "BEL",
          "BEN",
          "BES",
          "BFA",
          "BGD",
          "BGR",
          "BHR",
          "BHS",
          "BIH",
          "BLM",
          "BLR",
          "BLZ",
          "BMU",
          "BOL",
          "BRA",
          "BRB",
          "BRN",
          "BTN",
          "BVT",
          "BWA",
          "CAF",
          "CAN",
          "CCK",
          "CHE",
          "CHL",
          "CHN",
          "CIV",
          "CMR",
          "COD",
          "COG",
          "COK",
          "COL",
          "COM",
          "CPV",
          "CRI",
          "CUB",
          "CUW",
          "CXR",
          "CYM",
          "CYP",
          "CZE",
          "DEU",
          "DJI",
          "DMA",
          "DNK",
          "DOM",
          "DZA",
          "ECU",
          "EGY",
          "ERI",
          "ESH",
          "ESP",
          "EST",
          "ETH",
          "FIN",
          "FJI",
          "FLK",
          "FRA",
          "FRO",
          "FSM",
          "GAB",
          "GBR",
          "GEO",
          "GGY",
          "GHA",
          "GIB",
          "GIN",
          "GLP",
          "GMB",
          "GNB",
          "GNQ",
          "GRC",
          "GRD",
          "GRL",
          "GTM",
          "GUF",
          "GUM",
          "GUY",
          "HKG",
          "HMD",
          "HND",
          "HRV",
          "HTI",
          "HUN",
          "IDN",
          "IMN",
          "IND",
          "IOT",
          "IRL",
          "IRN",
          "IRQ",
          "ISL",
          "ISR",
          "ITA",
          "JAM",
          "JEY",
          "JOR",
          "JPN",
          "KAZ",
          "KEN",
          "KGZ",
          "KHM",
          "KIR",
          "KNA",
          "KOR",
          "KWT",
          "LAO",
          "LBN",
          "LBR",
          "LBY",
          "LCA",
          "LIE",
          "LKA",
          "LSO",
          "LTU",
          "LUX",
          "LVA",
          "MAC",
          "MAF",
          "MAR",
          "MCO",
          "MDA",
          "MDG",
          "MDV",
          "MEX",
          "MHL",
          "MKD",
          "MLI",
          "MLT",
          "MMR",
          "MNE",
          "MNG",
          "MNP",
          "MRT",
          "MSR",
          "MTQ",
          "MUS",
          "MWI",
          "MYS",
          "MYT",
          "NAM",
          "NCL",
          "NER",
          "NFK",
          "NGA",
          "NIC",
          "NIU",
          "NLD",
          "NOR",
          "NPL",
          "NRU",
          "NZL",
          "OMN",
          "PAK",
          "PAN",
          "PCN",
          "PER",
          "PHL",
          "PLW",
          "PNG",
          "POL",
          "PRI",
          "PRK",
          "PRT",
          "PRY",
          "PSE",
          "PYF",
          "QAT",
          "REU",
          "ROU",
          "RUS",
          "RWA",
          "SAU",
          "SDN",
          "SEN",
          "SGP",
          "SGS",
          "SHN",
          "SJM",
          "SLB",
          "SLE",
          "SLV",
          "SMR",
          "SOM",
          "SPM",
          "SRB",
          "SSD",
          "STP",
          "SUR",
          "SVK",
          "SVN",
          "SWE",
          "SWZ",
          "SXM",
          "SYC",
          "SYR",
          "TCA",
          "TCD",
          "TGO",
          "THA",
          "TJK",
          "TKL",
          "TKM",
          "TLS",
          "TON",
          "TTO",
          "TUN",
          "TUR",
          "TUV",
          "TWN",
          "TZA",
          "UGA",
          "UKR",
          "UMI",
          "URY",
          "USA",
          "UZB",
          "VAT",
          "VCT",
          "VEN",
          "VGB",
          "VIR",
          "VNM",
          "VUT",
          "WLF",
          "WSM",
          "XKX",
          "YEM",
          "ZAF",
          "ZMB",
          "ZWE"
        ],
        "nullable": true
      },
      "address": {
        "type": "object",
        "properties": {
          "line1": {
            "type": "string",
            "minLength": 1,
            "description": "First line of the address (max 35 characters).",
            "nullable": true
          },
          "line2": {
            "type": "string",
            "minLength": 1,
            "description": "Second line of the address (max 35 characters).",
            "nullable": true
          },
          "city": {
            "type": "string",
            "minLength": 1,
            "description": "City (max 20 characters).",
            "nullable": true
          },
          "region": {
            "type": "string",
            "minLength": 1,
            "description": "2-letter State code.",
            "nullable": true
          },
          "postal_code": {
            "type": "string",
            "minLength": 1,
            "description": "Zip or Postal code (max 7 characters).",
            "nullable": true
          },
          "country": {
            "$ref": "#/components/schemas/country"
          }
        },
        "required": [
          "city",
          "country",
          "line1",
          "postal_code",
          "region"
        ]
      },
      "nickname": {
        "type": "string",
        "description": "A human-readable name for the resource.",
        "nullable": true
      },
      "tags": {
        "type": "object",
        "title": "tags",
        "additionalProperties": true,
        "description": "Include up to 50 `key: value` pairs to annotate requests with custom metadata.\n- Maximum character length for individual `keys` is 40.\n- Maximum character length for individual `values` is 500.\n(For example, `order_number: 25`, `item_type: produce`, `department: sales`)",
        "nullable": true
      },
      "self": {
        "type": "object",
        "description": "Link to the resource that was used in the request.",
        "properties": {
          "href": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "subscription": {
        "title": "Subscription",
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/id"
          },
          "created_at": {
            "$ref": "#/components/schemas/created_at"
          },
          "updated_at": {
            "$ref": "#/components/schemas/updated_at"
          },
          "amount": {
            "$ref": "#/components/schemas/amount"
          },
          "application_id": {
            "type": "string",
            "description": "The ID of the `Application` associated with the `Subscription`."
          },
          "billing_cycle_day": {
            "$ref": "#/components/schemas/billing_cycle_day"
          },
          "billing_interval": {
            "$ref": "#/components/schemas/billing_interval"
          },
          "buyer_details": {
            "type": "object",
            "description": "An object containing details about the buyer.",
            "properties": {
              "identity_id": {
                "type": "string",
                "description": "The [identity ID](/api/identities) of the buyer."
              },
              "instrument_id": {
                "description": "The ID of the [`Payment Instrument`](/api/payment-instruments) from which the subscription payments get debited."
              },
              "requested_delivery_methods": {
                "$ref": "#/components/schemas/receipt_requested_delivery_methods"
              },
              "shipping_address": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/address"
                  }
                ],
                "nullable": true
              }
            }
          },
          "canceled_via": {
            "type": "string",
            "nullable": true,
            "description": "If the subscription was canceled, this field shows how the cancellation was initiated.\n\nPossible values:\n\n- `MERCHANT` - The customer (merchant) canceled the subscription themselves. The `linked_to` field indicates the related `Merchant`.\n- `AUTOMATED_OVERDUE` - The subscription was canceled by the overdue system.\n- `SUPPORT` - The subscription was canceled by Finix Support.\n",
            "enum": [
              "MERCHANT",
              "AUTOMATED_OVERDUE",
              "SUPPORT"
            ]
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 3-letter currency code.",
            "enum": [
              "USD",
              "CAD"
            ]
          },
          "end_subscription_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp of when the subscription ends. If `end_subscription_at` was included in the request, this field echoes that value. If only `total_billing_intervals` was provided, this field is calculated to match the last day of the final billing cycle."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "The date-time that the `Subscription` expires. Set when `total_billing_intervals` or `end_subscription_at` is provided. When `end_subscription_at` is set, this field mirrors that value."
          },
          "first_charge_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the first [Transfer](/api/transfers) will occur."
          },
          "linked_to": {
            "type": "string",
            "description": "The ID of the [Merchant](/api/merchants) resource that you wish to link to the `Subscription` (i.e., the merchant that the subscription belongs to).\n\nAt this time, only approved merchants with one of the following processors are valid:\n\n- `DUMMY_V1`\n- `FINIX_V1`\n"
          },
          "linked_type": {
            "type": "string",
            "description": "The type of the resource that is specified in the `linked_to` field.",
            "enum": [
              "MERCHANT"
            ]
          },
          "next_billing_date": {
            "type": "object",
            "description": "Details when the next [Transfer](/api/transfers) will occur.",
            "properties": {
              "year": {
                "type": "integer",
                "description": "The year the next `Transfer` will occur."
              },
              "month": {
                "type": "integer",
                "description": "The month the next `Transfer` will occur."
              },
              "day": {
                "type": "integer",
                "description": "The day the next `Transfer` will occur."
              }
            }
          },
          "nickname": {
            "$ref": "#/components/schemas/nickname"
          },
          "start_subscription_at": {
            "type": "string",
            "format": "date-time",
            "description": "Indicates that the subscription is scheduled to begin in the future. The timestamp specifies the exact start date for subscription billing."
          },
          "state": {
            "type": "string",
            "description": "The state of the `Subscription`.\n\n- The `NOT_STARTED` state occurs when the subscription has not yet started, typically indicated by a `start_subscription_at` timestamp set during creation.\n- A subscription in the `PAST_DUE` state is unpaid but has not yet been canceled.\n",
            "enum": [
              "ACTIVE",
              "CANCELED",
              "EXPIRED",
              "NOT_STARTED",
              "PAST_DUE"
            ]
          },
          "subscription_details": {
            "type": "object",
            "description": "An object containing subscription details.",
            "properties": {
              "collection_method": {
                "type": "string",
                "description": "The method by which subscription payments are collected. Currently, automatic billing of the `Payment Instrument` is the only available method.",
                "enum": [
                  "BILL_AUTOMATICALLY"
                ]
              },
              "send_invoice": {
                "type": "boolean",
                "description": "Whether to send the user an invoice."
              },
              "send_receipt": {
                "type": "boolean",
                "description": "Whether to send the user a receipt."
              },
              "trial_details": {
                "type": "object",
                "nullable": true,
                "description": "Object containing trial details.",
                "properties": {
                  "interval_type": {
                    "type": "string",
                    "description": "The unit of time for the trial period.",
                    "enum": [
                      "DAY",
                      "WEEK",
                      "MONTH",
                      "YEAR"
                    ]
                  },
                  "interval_count": {
                    "type": "integer",
                    "description": "The number of intervals of `interval_type` used to describe the duration of the trial."
                  },
                  "trial_started_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "A timestamp indicating when the trial period began.",
                    "nullable": true
                  },
                  "trial_expected_start_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "A timestamp indicating when the trial period is expected to start."
                  },
                  "trial_expected_end_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "A timestamp indicating when the trial period ends."
                  }
                }
              },
              "discount_phase_details": {
                "type": "object",
                "nullable": true,
                "description": "Object containing discount phase details.",
                "properties": {
                  "amount": {
                    "type": "integer",
                    "description": "The discounted amount (in cents) that the buyer is charged during the discount phase."
                  },
                  "billing_interval_count": {
                    "type": "integer",
                    "description": "The number of billing intervals the discount applies. After this period, the buyer is charged the full `amount` from the `Subscription`."
                  },
                  "discount_phase_started_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "A timestamp indicating when the discount phase began.",
                    "nullable": true
                  },
                  "discount_phase_expected_start_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "A timestamp indicating when the discount phase is expected to start."
                  },
                  "discount_phase_expected_end_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "A timestamp indicating when the discount phase is expected to end."
                  }
                }
              },
              "notification_preferences": {
                "type": "object",
                "description": "Object containing notification preferences.",
                "properties": {
                  "send_confirmation": {
                    "type": "boolean",
                    "description": "Whether to send a confirmation email to the user.",
                    "default": false
                  }
                }
              }
            },
            "required": [
              "collection_method"
            ]
          },
          "subscription_link_id": {
            "type": "string",
            "description": "The ID of the `Subscription Link` that created the `Subscription`.",
            "nullable": true
          },
          "subscription_phase": {
            "type": "string",
            "description": "Indicates the period within a subscription where specific rules apply.\n\n- `EVERGREEN` - The buyer is billed continuously for the subscription until the subscription is canceled.\n- `DISCOUNT` - The buyer receives a discounted price for a limited billing interval, after which the customer is charged the full subscription amount.\n- `FIXED` state - Applicable to fixed-length subscriptions.\n- `NONE` - Indicates that when the `start_subscription_at` timestamp is set during subscription creation, the subscription is not yet in any phase, and billing has not started.\n- `TRIAL` - The period during which the buyer is not billed; after this phase, the buyer will begin being billed.\n",
            "enum": [
              "EVERGREEN",
              "DISCOUNT",
              "FIXED",
              "NONE",
              "TRIAL"
            ]
          },
          "subscription_plan_id": {
            "type": "string",
            "nullable": true,
            "description": "The ID of a [Subscription Plan](/api/subscription-plans) from which this `Subscription` was created. When provided, the plan's `amount`, `billing_interval`, and other defaults are inherited.",
            "example": "subscription_plan_ctBbJ1ihsC8Hpju4RQfZE"
          },
          "has_usage_based_plan": {
            "type": "boolean",
            "description": "Indicates whether the `Subscription` is associated with a usage-based `Subscription Plan`.",
            "nullable": true
          },
          "tags": {
            "$ref": "#/components/schemas/tags"
          },
          "total_billing_intervals": {
            "type": "integer",
            "nullable": true,
            "description": "The total number of billing intervals for the `Subscription`. This represents the total count of recurring billing cycles, such as months or weeks, depending on the billing frequency."
          },
          "_links": {
            "type": "object",
            "description": "An object containing link(s) relevant to the request. You can store these links for follow-up requests.",
            "properties": {
              "self": {
                "$ref": "#/components/schemas/self"
              }
            }
          }
        }
      }
    }
  }
}
```

## Creating a Subscription from a Subscription plan via the API with a start date

You can specify a start date for a `Subscription` that uses a [Subscription Plan](/guides/subscriptions/subscription-plans).

To do so, include a `start_subscription_at` timestamp in the request body:

Example
```shell cURL
curl -i -X POST \
  -u '<username>:<password>' \
  https://finix.sandbox-payments-api.com/subscriptions \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "buyer_details": {
      "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S",
      "instrument_id": "PImXAVgkKVshKWWHUk4xXbve"
    },
    "linked_to": "MUxdJCr9xTMnmt1vGUAqV9z4",
    "linked_type": "MERCHANT",
    "start_subscription_at": "2027-06-01T00:00:00.000Z",
    "subscription_plan_id": "subscription_plan_ctBbJ1ihsC8Hpju4RQfZE"
  }'
```

API Definition
```json
{
  "$ref": "#/components/schemas/createSubscriptionFromPlan",
  "components": {
    "schemas": {
      "receipt_requested_delivery_methods": {
        "type": "array",
        "description": "A list of requested delivery methods. Each method specifies\nthe type of delivery and the destination(s) where the receipt should be sent.\n",
        "items": {
          "type": "object",
          "required": [
            "type",
            "destinations"
          ],
          "properties": {
            "type": {
              "type": "string",
              "description": "The method of receipt delivery.\n",
              "enum": [
                "EMAIL",
                "SMS",
                "PRINT"
              ]
            },
            "destinations": {
              "type": "array",
              "description": "A list of destination addresses or identifiers where the receipt should be sent.\n",
              "items": {
                "type": "string"
              },
              "minItems": 1
            }
          }
        }
      },
      "country": {
        "type": "string",
        "enum": [
          "ABW",
          "AFG",
          "AGO",
          "AIA",
          "ALA",
          "ALB",
          "AND",
          "ARE",
          "ARG",
          "ARM",
          "ASM",
          "ATA",
          "ATF",
          "ATG",
          "AUS",
          "AUT",
          "AZE",
          "BDI",
          "BEL",
          "BEN",
          "BES",
          "BFA",
          "BGD",
          "BGR",
          "BHR",
          "BHS",
          "BIH",
          "BLM",
          "BLR",
          "BLZ",
          "BMU",
          "BOL",
          "BRA",
          "BRB",
          "BRN",
          "BTN",
          "BVT",
          "BWA",
          "CAF",
          "CAN",
          "CCK",
          "CHE",
          "CHL",
          "CHN",
          "CIV",
          "CMR",
          "COD",
          "COG",
          "COK",
          "COL",
          "COM",
          "CPV",
          "CRI",
          "CUB",
          "CUW",
          "CXR",
          "CYM",
          "CYP",
          "CZE",
          "DEU",
          "DJI",
          "DMA",
          "DNK",
          "DOM",
          "DZA",
          "ECU",
          "EGY",
          "ERI",
          "ESH",
          "ESP",
          "EST",
          "ETH",
          "FIN",
          "FJI",
          "FLK",
          "FRA",
          "FRO",
          "FSM",
          "GAB",
          "GBR",
          "GEO",
          "GGY",
          "GHA",
          "GIB",
          "GIN",
          "GLP",
          "GMB",
          "GNB",
          "GNQ",
          "GRC",
          "GRD",
          "GRL",
          "GTM",
          "GUF",
          "GUM",
          "GUY",
          "HKG",
          "HMD",
          "HND",
          "HRV",
          "HTI",
          "HUN",
          "IDN",
          "IMN",
          "IND",
          "IOT",
          "IRL",
          "IRN",
          "IRQ",
          "ISL",
          "ISR",
          "ITA",
          "JAM",
          "JEY",
          "JOR",
          "JPN",
          "KAZ",
          "KEN",
          "KGZ",
          "KHM",
          "KIR",
          "KNA",
          "KOR",
          "KWT",
          "LAO",
          "LBN",
          "LBR",
          "LBY",
          "LCA",
          "LIE",
          "LKA",
          "LSO",
          "LTU",
          "LUX",
          "LVA",
          "MAC",
          "MAF",
          "MAR",
          "MCO",
          "MDA",
          "MDG",
          "MDV",
          "MEX",
          "MHL",
          "MKD",
          "MLI",
          "MLT",
          "MMR",
          "MNE",
          "MNG",
          "MNP",
          "MRT",
          "MSR",
          "MTQ",
          "MUS",
          "MWI",
          "MYS",
          "MYT",
          "NAM",
          "NCL",
          "NER",
          "NFK",
          "NGA",
          "NIC",
          "NIU",
          "NLD",
          "NOR",
          "NPL",
          "NRU",
          "NZL",
          "OMN",
          "PAK",
          "PAN",
          "PCN",
          "PER",
          "PHL",
          "PLW",
          "PNG",
          "POL",
          "PRI",
          "PRK",
          "PRT",
          "PRY",
          "PSE",
          "PYF",
          "QAT",
          "REU",
          "ROU",
          "RUS",
          "RWA",
          "SAU",
          "SDN",
          "SEN",
          "SGP",
          "SGS",
          "SHN",
          "SJM",
          "SLB",
          "SLE",
          "SLV",
          "SMR",
          "SOM",
          "SPM",
          "SRB",
          "SSD",
          "STP",
          "SUR",
          "SVK",
          "SVN",
          "SWE",
          "SWZ",
          "SXM",
          "SYC",
          "SYR",
          "TCA",
          "TCD",
          "TGO",
          "THA",
          "TJK",
          "TKL",
          "TKM",
          "TLS",
          "TON",
          "TTO",
          "TUN",
          "TUR",
          "TUV",
          "TWN",
          "TZA",
          "UGA",
          "UKR",
          "UMI",
          "URY",
          "USA",
          "UZB",
          "VAT",
          "VCT",
          "VEN",
          "VGB",
          "VIR",
          "VNM",
          "VUT",
          "WLF",
          "WSM",
          "XKX",
          "YEM",
          "ZAF",
          "ZMB",
          "ZWE"
        ],
        "nullable": true
      },
      "address": {
        "type": "object",
        "properties": {
          "line1": {
            "type": "string",
            "minLength": 1,
            "description": "First line of the address (max 35 characters).",
            "nullable": true
          },
          "line2": {
            "type": "string",
            "minLength": 1,
            "description": "Second line of the address (max 35 characters).",
            "nullable": true
          },
          "city": {
            "type": "string",
            "minLength": 1,
            "description": "City (max 20 characters).",
            "nullable": true
          },
          "region": {
            "type": "string",
            "minLength": 1,
            "description": "2-letter State code.",
            "nullable": true
          },
          "postal_code": {
            "type": "string",
            "minLength": 1,
            "description": "Zip or Postal code (max 7 characters).",
            "nullable": true
          },
          "country": {
            "$ref": "#/components/schemas/country"
          }
        },
        "required": [
          "city",
          "country",
          "line1",
          "postal_code",
          "region"
        ]
      },
      "end_subscription_at": {
        "type": "string",
        "format": "date-time",
        "nullable": true,
        "description": "Timestamp of when the subscription ends. Applies to fixed amount subscriptions only.\n\nFinix prorates the final charge if the subscription ends mid-billing-cycle. If `end_subscription_at` falls on a cycle boundary, the final charge is not prorated.\n\nThe following rules apply:\n\n- Cannot be used with `total_billing_intervals` in the same request.\n- Must be after the subscription start.\n- Must be after the free trial period.\n- Must be after the discounted phase.\n- Cannot be updated after the subscription is created.\n\n**Relationship with `total_billing_intervals` and `expires_at`:**\n\n- If `end_subscription_at` is provided, `total_billing_intervals` in the response is calculated as the number of started cycles needed to reach the end date.\n- If `total_billing_intervals` is provided, `end_subscription_at` in the response is calculated to match the last day of the final cycle.\n- Setting `end_subscription_at` also sets `expires_at` to the same value in the response.\n"
      },
      "nickname": {
        "type": "string",
        "description": "A human-readable name for the resource.",
        "nullable": true
      },
      "tags": {
        "type": "object",
        "title": "tags",
        "additionalProperties": true,
        "description": "Include up to 50 `key: value` pairs to annotate requests with custom metadata.\n- Maximum character length for individual `keys` is 40.\n- Maximum character length for individual `values` is 500.\n(For example, `order_number: 25`, `item_type: produce`, `department: sales`)",
        "nullable": true
      },
      "total_billing_intervals": {
        "type": "integer",
        "nullable": true,
        "description": "The total number of billing cycles for the `Subscription`. Cannot be used with `end_subscription_at` in the same request and cannot be updated after the subscription is created.\n\n**Relationship with `end_subscription_at`:**\n\n- If `total_billing_intervals` is provided, `end_subscription_at` in the response is calculated to match the last day of the final cycle.\n- If `end_subscription_at` is provided, `total_billing_intervals` in the response is calculated as the number of started cycles needed to reach the end date.\n",
        "example": 12
      },
      "createSubscriptionFromPlan": {
        "title": "Subscription - Subscription Plan - All Fields",
        "properties": {
          "buyer_details": {
            "type": "object",
            "description": "An object containing details about the buyer.",
            "properties": {
              "identity_id": {
                "type": "string",
                "description": "The [identity ID](/api/identities) of the buyer.",
                "example": "IDtEnKsZyJNUGK83ZTx4C45S"
              },
              "instrument_id": {
                "description": "The ID of the [`Payment Instrument`](/api/payment-instruments) from which the subscription payments get debited.",
                "example": "PImXAVgkKVshKWWHUk4xXbve"
              },
              "requested_delivery_methods": {
                "$ref": "#/components/schemas/receipt_requested_delivery_methods"
              },
              "shipping_address": {
                "$ref": "#/components/schemas/address"
              }
            },
            "required": [
              "identity_id",
              "instrument_id"
            ]
          },
          "end_subscription_at": {
            "$ref": "#/components/schemas/end_subscription_at"
          },
          "linked_to": {
            "type": "string",
            "description": "The ID of the [Merchant](/api/merchants) resource that you wish to link to the `Subscription` (i.e., the merchant that the subscription belongs to).\n\nAt this time, only approved merchants with one of the following processors are valid:\n\n- `DUMMY_V1`\n- `FINIX_V1`\n",
            "example": "MUxdJCr9xTMnmt1vGUAqV9z4"
          },
          "linked_type": {
            "type": "string",
            "description": "The type of the resource that is specified in the `linked_to` field.",
            "example": "MERCHANT",
            "enum": [
              "MERCHANT"
            ]
          },
          "nickname": {
            "$ref": "#/components/schemas/nickname"
          },
          "start_subscription_at": {
            "type": "string",
            "format": "date-time",
            "description": "Indicates that the subscription is scheduled to begin in the future. The timestamp specifies the exact start date for subscription billing.",
            "example": "2029-05-05T22:42:05.490Z"
          },
          "subscription_plan_id": {
            "type": "string",
            "description": "The ID of the `Subscription Plan` from which to create the `Subscription`.",
            "example": "subscription_plan_ctBbJ1ihsC8Hpju4RQfZE"
          },
          "tags": {
            "$ref": "#/components/schemas/tags"
          },
          "total_billing_intervals": {
            "$ref": "#/components/schemas/total_billing_intervals"
          }
        },
        "required": [
          "buyer_details",
          "linked_to",
          "linked_type",
          "subscription_plan_id"
        ]
      }
    }
  }
}
```

Example
Subscription - From Subscription Plan - Future Start Date
```json Subscription - From Subscription Plan - Future Start Date
{
  "id" : "subscription_cA2DeRbnuvrPQHK2HooT7",
  "created_at" : "2026-05-14T14:46:30.73Z",
  "updated_at" : "2026-05-14T14:46:30.73Z",
  "amount" : 19900,
  "application_id" : "APc9vhYcPsRuTSpKD9KpMtPe",
  "billing_interval" : "MONTHLY",
  "buyer_details" : {
    "identity_id" : "IDtEnKsZyJNUGK83ZTx4C45S",
    "instrument_id" : "PImXAVgkKVshKWWHUk4xXbve",
    "requested_delivery_methods" : [ {
      "type" : "EMAIL",
      "destinations" : [ "abc@test.com" ]
    }, {
      "type" : "SMS",
      "destinations" : [ "2348765431" ]
    } ],
    "shipping_address" : {
      "city" : "Middletown",
      "country" : "USA",
      "line1" : "324 Oak Avenue",
      "line2" : "Apartment 7",
      "postal_code" : "19734",
      "region" : "DE"
    }
  },
  "canceled_via" : null,
  "currency" : "USD",
  "expires_at" : "2028-06-01T00:00:00.000Z",
  "first_charge_at" : "2027-06-01T00:00:00.000Z",
  "has_usage_based_plan" : false,
  "linked_to" : "MUxdJCr9xTMnmt1vGUAqV9z4",
  "linked_type" : "MERCHANT",
  "next_billing_date" : {
    "year" : 2027,
    "month" : 6,
    "day" : 1
  },
  "nickname" : "Finflix Gold Package",
  "start_subscription_at" : "2027-06-01T00:00:00.000Z",
  "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" : "subscription_plan_ctBbJ1ihsC8Hpju4RQfZE", // [!code highlight]
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "total_billing_intervals" : 12,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/subscriptions/subscription_cA2DeRbnuvrPQHK2HooT7"
    }
  }
}
```

API Definition
```json
{
  "$ref": "#/components/schemas/subscription",
  "components": {
    "schemas": {
      "id": {
        "type": "string",
        "minLength": 1,
        "description": "The ID of the resource."
      },
      "created_at": {
        "type": "string",
        "format": "date-time",
        "description": "Timestamp of when the object was created."
      },
      "updated_at": {
        "type": "string",
        "format": "date-time",
        "description": "Timestamp of when the object was last updated."
      },
      "amount": {
        "type": "integer",
        "description": "The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).",
        "example": 5000,
        "format": "int64"
      },
      "billing_cycle_day": {
        "type": "integer",
        "description": "The day of the month on which the `Subscription` is billed. Only applies to subscriptions with a monthly billing cycle (e.g., `MONTHLY`, `BIMONTHLY`, `QUARTERLY`, `SEMIYEARLY`, `YEARLY`, `BIYEARLY`, `TRIYEARLY`).\n\nIf the specified day doesn't exist in a given month (e.g., April 31), the subscription is billed on the last valid day of that month.\n\nAccepted values are 1 to 31.\n",
        "minimum": 1,
        "maximum": 31,
        "example": 1,
        "nullable": true
      },
      "billing_interval": {
        "type": "string",
        "description": "How often the buyer is billed. The possible billing intervals are as follows:\n\n- `BIMONTHLY`: every 2 months\n- `BIWEEKLY`: every 2 weeks\n- `BIYEARLY`: every 2 years\n- `DAILY`: every day\n- `MONTHLY`: every month\n- `QUARTERLY`: each quarter\n- `SEMIYEARLY`: twice a year\n- `TRIYEARLY`: every 3 years\n- `WEEKLY`: every week\n- `YEARLY`: every year\n",
        "example": "MONTHLY",
        "enum": [
          "BIMONTHLY",
          "BIWEEKLY",
          "BIYEARLY",
          "DAILY",
          "MONTHLY",
          "QUARTERLY",
          "SEMIYEARLY",
          "TRIYEARLY",
          "WEEKLY",
          "YEARLY"
        ]
      },
      "receipt_requested_delivery_methods": {
        "type": "array",
        "description": "A list of requested delivery methods. Each method specifies\nthe type of delivery and the destination(s) where the receipt should be sent.\n",
        "items": {
          "type": "object",
          "required": [
            "type",
            "destinations"
          ],
          "properties": {
            "type": {
              "type": "string",
              "description": "The method of receipt delivery.\n",
              "enum": [
                "EMAIL",
                "SMS",
                "PRINT"
              ]
            },
            "destinations": {
              "type": "array",
              "description": "A list of destination addresses or identifiers where the receipt should be sent.\n",
              "items": {
                "type": "string"
              },
              "minItems": 1
            }
          }
        }
      },
      "country": {
        "type": "string",
        "enum": [
          "ABW",
          "AFG",
          "AGO",
          "AIA",
          "ALA",
          "ALB",
          "AND",
          "ARE",
          "ARG",
          "ARM",
          "ASM",
          "ATA",
          "ATF",
          "ATG",
          "AUS",
          "AUT",
          "AZE",
          "BDI",
          "BEL",
          "BEN",
          "BES",
          "BFA",
          "BGD",
          "BGR",
          "BHR",
          "BHS",
          "BIH",
          "BLM",
          "BLR",
          "BLZ",
          "BMU",
          "BOL",
          "BRA",
          "BRB",
          "BRN",
          "BTN",
          "BVT",
          "BWA",
          "CAF",
          "CAN",
          "CCK",
          "CHE",
          "CHL",
          "CHN",
          "CIV",
          "CMR",
          "COD",
          "COG",
          "COK",
          "COL",
          "COM",
          "CPV",
          "CRI",
          "CUB",
          "CUW",
          "CXR",
          "CYM",
          "CYP",
          "CZE",
          "DEU",
          "DJI",
          "DMA",
          "DNK",
          "DOM",
          "DZA",
          "ECU",
          "EGY",
          "ERI",
          "ESH",
          "ESP",
          "EST",
          "ETH",
          "FIN",
          "FJI",
          "FLK",
          "FRA",
          "FRO",
          "FSM",
          "GAB",
          "GBR",
          "GEO",
          "GGY",
          "GHA",
          "GIB",
          "GIN",
          "GLP",
          "GMB",
          "GNB",
          "GNQ",
          "GRC",
          "GRD",
          "GRL",
          "GTM",
          "GUF",
          "GUM",
          "GUY",
          "HKG",
          "HMD",
          "HND",
          "HRV",
          "HTI",
          "HUN",
          "IDN",
          "IMN",
          "IND",
          "IOT",
          "IRL",
          "IRN",
          "IRQ",
          "ISL",
          "ISR",
          "ITA",
          "JAM",
          "JEY",
          "JOR",
          "JPN",
          "KAZ",
          "KEN",
          "KGZ",
          "KHM",
          "KIR",
          "KNA",
          "KOR",
          "KWT",
          "LAO",
          "LBN",
          "LBR",
          "LBY",
          "LCA",
          "LIE",
          "LKA",
          "LSO",
          "LTU",
          "LUX",
          "LVA",
          "MAC",
          "MAF",
          "MAR",
          "MCO",
          "MDA",
          "MDG",
          "MDV",
          "MEX",
          "MHL",
          "MKD",
          "MLI",
          "MLT",
          "MMR",
          "MNE",
          "MNG",
          "MNP",
          "MRT",
          "MSR",
          "MTQ",
          "MUS",
          "MWI",
          "MYS",
          "MYT",
          "NAM",
          "NCL",
          "NER",
          "NFK",
          "NGA",
          "NIC",
          "NIU",
          "NLD",
          "NOR",
          "NPL",
          "NRU",
          "NZL",
          "OMN",
          "PAK",
          "PAN",
          "PCN",
          "PER",
          "PHL",
          "PLW",
          "PNG",
          "POL",
          "PRI",
          "PRK",
          "PRT",
          "PRY",
          "PSE",
          "PYF",
          "QAT",
          "REU",
          "ROU",
          "RUS",
          "RWA",
          "SAU",
          "SDN",
          "SEN",
          "SGP",
          "SGS",
          "SHN",
          "SJM",
          "SLB",
          "SLE",
          "SLV",
          "SMR",
          "SOM",
          "SPM",
          "SRB",
          "SSD",
          "STP",
          "SUR",
          "SVK",
          "SVN",
          "SWE",
          "SWZ",
          "SXM",
          "SYC",
          "SYR",
          "TCA",
          "TCD",
          "TGO",
          "THA",
          "TJK",
          "TKL",
          "TKM",
          "TLS",
          "TON",
          "TTO",
          "TUN",
          "TUR",
          "TUV",
          "TWN",
          "TZA",
          "UGA",
          "UKR",
          "UMI",
          "URY",
          "USA",
          "UZB",
          "VAT",
          "VCT",
          "VEN",
          "VGB",
          "VIR",
          "VNM",
          "VUT",
          "WLF",
          "WSM",
          "XKX",
          "YEM",
          "ZAF",
          "ZMB",
          "ZWE"
        ],
        "nullable": true
      },
      "address": {
        "type": "object",
        "properties": {
          "line1": {
            "type": "string",
            "minLength": 1,
            "description": "First line of the address (max 35 characters).",
            "nullable": true
          },
          "line2": {
            "type": "string",
            "minLength": 1,
            "description": "Second line of the address (max 35 characters).",
            "nullable": true
          },
          "city": {
            "type": "string",
            "minLength": 1,
            "description": "City (max 20 characters).",
            "nullable": true
          },
          "region": {
            "type": "string",
            "minLength": 1,
            "description": "2-letter State code.",
            "nullable": true
          },
          "postal_code": {
            "type": "string",
            "minLength": 1,
            "description": "Zip or Postal code (max 7 characters).",
            "nullable": true
          },
          "country": {
            "$ref": "#/components/schemas/country"
          }
        },
        "required": [
          "city",
          "country",
          "line1",
          "postal_code",
          "region"
        ]
      },
      "nickname": {
        "type": "string",
        "description": "A human-readable name for the resource.",
        "nullable": true
      },
      "tags": {
        "type": "object",
        "title": "tags",
        "additionalProperties": true,
        "description": "Include up to 50 `key: value` pairs to annotate requests with custom metadata.\n- Maximum character length for individual `keys` is 40.\n- Maximum character length for individual `values` is 500.\n(For example, `order_number: 25`, `item_type: produce`, `department: sales`)",
        "nullable": true
      },
      "self": {
        "type": "object",
        "description": "Link to the resource that was used in the request.",
        "properties": {
          "href": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "subscription": {
        "title": "Subscription",
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/id"
          },
          "created_at": {
            "$ref": "#/components/schemas/created_at"
          },
          "updated_at": {
            "$ref": "#/components/schemas/updated_at"
          },
          "amount": {
            "$ref": "#/components/schemas/amount"
          },
          "application_id": {
            "type": "string",
            "description": "The ID of the `Application` associated with the `Subscription`."
          },
          "billing_cycle_day": {
            "$ref": "#/components/schemas/billing_cycle_day"
          },
          "billing_interval": {
            "$ref": "#/components/schemas/billing_interval"
          },
          "buyer_details": {
            "type": "object",
            "description": "An object containing details about the buyer.",
            "properties": {
              "identity_id": {
                "type": "string",
                "description": "The [identity ID](/api/identities) of the buyer."
              },
              "instrument_id": {
                "description": "The ID of the [`Payment Instrument`](/api/payment-instruments) from which the subscription payments get debited."
              },
              "requested_delivery_methods": {
                "$ref": "#/components/schemas/receipt_requested_delivery_methods"
              },
              "shipping_address": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/address"
                  }
                ],
                "nullable": true
              }
            }
          },
          "canceled_via": {
            "type": "string",
            "nullable": true,
            "description": "If the subscription was canceled, this field shows how the cancellation was initiated.\n\nPossible values:\n\n- `MERCHANT` - The customer (merchant) canceled the subscription themselves. The `linked_to` field indicates the related `Merchant`.\n- `AUTOMATED_OVERDUE` - The subscription was canceled by the overdue system.\n- `SUPPORT` - The subscription was canceled by Finix Support.\n",
            "enum": [
              "MERCHANT",
              "AUTOMATED_OVERDUE",
              "SUPPORT"
            ]
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 3-letter currency code.",
            "enum": [
              "USD",
              "CAD"
            ]
          },
          "end_subscription_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp of when the subscription ends. If `end_subscription_at` was included in the request, this field echoes that value. If only `total_billing_intervals` was provided, this field is calculated to match the last day of the final billing cycle."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "The date-time that the `Subscription` expires. Set when `total_billing_intervals` or `end_subscription_at` is provided. When `end_subscription_at` is set, this field mirrors that value."
          },
          "first_charge_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the first [Transfer](/api/transfers) will occur."
          },
          "linked_to": {
            "type": "string",
            "description": "The ID of the [Merchant](/api/merchants) resource that you wish to link to the `Subscription` (i.e., the merchant that the subscription belongs to).\n\nAt this time, only approved merchants with one of the following processors are valid:\n\n- `DUMMY_V1`\n- `FINIX_V1`\n"
          },
          "linked_type": {
            "type": "string",
            "description": "The type of the resource that is specified in the `linked_to` field.",
            "enum": [
              "MERCHANT"
            ]
          },
          "next_billing_date": {
            "type": "object",
            "description": "Details when the next [Transfer](/api/transfers) will occur.",
            "properties": {
              "year": {
                "type": "integer",
                "description": "The year the next `Transfer` will occur."
              },
              "month": {
                "type": "integer",
                "description": "The month the next `Transfer` will occur."
              },
              "day": {
                "type": "integer",
                "description": "The day the next `Transfer` will occur."
              }
            }
          },
          "nickname": {
            "$ref": "#/components/schemas/nickname"
          },
          "start_subscription_at": {
            "type": "string",
            "format": "date-time",
            "description": "Indicates that the subscription is scheduled to begin in the future. The timestamp specifies the exact start date for subscription billing."
          },
          "state": {
            "type": "string",
            "description": "The state of the `Subscription`.\n\n- The `NOT_STARTED` state occurs when the subscription has not yet started, typically indicated by a `start_subscription_at` timestamp set during creation.\n- A subscription in the `PAST_DUE` state is unpaid but has not yet been canceled.\n",
            "enum": [
              "ACTIVE",
              "CANCELED",
              "EXPIRED",
              "NOT_STARTED",
              "PAST_DUE"
            ]
          },
          "subscription_details": {
            "type": "object",
            "description": "An object containing subscription details.",
            "properties": {
              "collection_method": {
                "type": "string",
                "description": "The method by which subscription payments are collected. Currently, automatic billing of the `Payment Instrument` is the only available method.",
                "enum": [
                  "BILL_AUTOMATICALLY"
                ]
              },
              "send_invoice": {
                "type": "boolean",
                "description": "Whether to send the user an invoice."
              },
              "send_receipt": {
                "type": "boolean",
                "description": "Whether to send the user a receipt."
              },
              "trial_details": {
                "type": "object",
                "nullable": true,
                "description": "Object containing trial details.",
                "properties": {
                  "interval_type": {
                    "type": "string",
                    "description": "The unit of time for the trial period.",
                    "enum": [
                      "DAY",
                      "WEEK",
                      "MONTH",
                      "YEAR"
                    ]
                  },
                  "interval_count": {
                    "type": "integer",
                    "description": "The number of intervals of `interval_type` used to describe the duration of the trial."
                  },
                  "trial_started_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "A timestamp indicating when the trial period began.",
                    "nullable": true
                  },
                  "trial_expected_start_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "A timestamp indicating when the trial period is expected to start."
                  },
                  "trial_expected_end_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "A timestamp indicating when the trial period ends."
                  }
                }
              },
              "discount_phase_details": {
                "type": "object",
                "nullable": true,
                "description": "Object containing discount phase details.",
                "properties": {
                  "amount": {
                    "type": "integer",
                    "description": "The discounted amount (in cents) that the buyer is charged during the discount phase."
                  },
                  "billing_interval_count": {
                    "type": "integer",
                    "description": "The number of billing intervals the discount applies. After this period, the buyer is charged the full `amount` from the `Subscription`."
                  },
                  "discount_phase_started_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "A timestamp indicating when the discount phase began.",
                    "nullable": true
                  },
                  "discount_phase_expected_start_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "A timestamp indicating when the discount phase is expected to start."
                  },
                  "discount_phase_expected_end_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "A timestamp indicating when the discount phase is expected to end."
                  }
                }
              },
              "notification_preferences": {
                "type": "object",
                "description": "Object containing notification preferences.",
                "properties": {
                  "send_confirmation": {
                    "type": "boolean",
                    "description": "Whether to send a confirmation email to the user.",
                    "default": false
                  }
                }
              }
            },
            "required": [
              "collection_method"
            ]
          },
          "subscription_link_id": {
            "type": "string",
            "description": "The ID of the `Subscription Link` that created the `Subscription`.",
            "nullable": true
          },
          "subscription_phase": {
            "type": "string",
            "description": "Indicates the period within a subscription where specific rules apply.\n\n- `EVERGREEN` - The buyer is billed continuously for the subscription until the subscription is canceled.\n- `DISCOUNT` - The buyer receives a discounted price for a limited billing interval, after which the customer is charged the full subscription amount.\n- `FIXED` state - Applicable to fixed-length subscriptions.\n- `NONE` - Indicates that when the `start_subscription_at` timestamp is set during subscription creation, the subscription is not yet in any phase, and billing has not started.\n- `TRIAL` - The period during which the buyer is not billed; after this phase, the buyer will begin being billed.\n",
            "enum": [
              "EVERGREEN",
              "DISCOUNT",
              "FIXED",
              "NONE",
              "TRIAL"
            ]
          },
          "subscription_plan_id": {
            "type": "string",
            "nullable": true,
            "description": "The ID of a [Subscription Plan](/api/subscription-plans) from which this `Subscription` was created. When provided, the plan's `amount`, `billing_interval`, and other defaults are inherited.",
            "example": "subscription_plan_ctBbJ1ihsC8Hpju4RQfZE"
          },
          "has_usage_based_plan": {
            "type": "boolean",
            "description": "Indicates whether the `Subscription` is associated with a usage-based `Subscription Plan`.",
            "nullable": true
          },
          "tags": {
            "$ref": "#/components/schemas/tags"
          },
          "total_billing_intervals": {
            "type": "integer",
            "nullable": true,
            "description": "The total number of billing intervals for the `Subscription`. This represents the total count of recurring billing cycles, such as months or weeks, depending on the billing frequency."
          },
          "_links": {
            "type": "object",
            "description": "An object containing link(s) relevant to the request. You can store these links for follow-up requests.",
            "properties": {
              "self": {
                "$ref": "#/components/schemas/self"
              }
            }
          }
        }
      }
    }
  }
}
```