# List Subscription Plans

Retrieve a list of Subscription Plan resources.

Endpoint: GET /subscription_plans
Version: 2022-02-01
Security: BasicAuth

## Header parameters:

  - `Finix-Version` (string)
    Specify the API version of your request. For more details, see Versioning.
    Example: "2022-02-01"

## Query parameters:

  - `amount.gt` (integer)
    Filter by an amount greater than.
    Example: 100

  - `amount.gte` (integer)
    Filter by an amount greater than or equal.
    Example: 100

  - `amount.lt` (integer)
    Filter by an amount less than.
    Example: 100

  - `amount.lte` (integer)
    Filter by an amount less than or equal.
    Example: 100

  - `amount` (integer)
    Filter by an amount equal to the given value.
    Example: 100

  - `linked_to` (string)
    Filter subscription plans linked to a specific Merchant.
    Example: "MUcgYZswyRfqSSbvMsxuaHxZ"

  - `state` (string)
    Filter by state:
- ACTIVE
- INACTIVE
    Example: "INACTIVE"

  - `application_id` (string)
    Filter by Application ID.
    Example: "APc9vhYcPsRuTSpKD9KpMtPe"

  - `after_cursor` (string)
    Return every resource created after the cursor value.

  - `before_cursor` (string)
    Return every resource created before the cursor value.

  - `created_at.gte` (string)
    Filter where created_at is after the given date.
    Example: "2022-09-27T11:21:23"

  - `created_at.lte` (string)
    Filter where created_at is before the given date.
    Example: "2026-09-27T11:21:23"

  - `limit` (integer)
    The numbers of items to return.
    Example: 10

  - `tags.key` (string)
    Filter by the tag's key. For more information, see Tags.
    Example: "card_type"

  - `tags.value` (string)
    Filter by the tag's value. For more information, see Tags.
    Example: "business_card"

  - `updated_at.gte` (string)
    Filter where updated_at is after the given date.
    Example: "2022-09-27T11:21:23"

  - `updated_at.lte` (string)
    Filter where updated_at is before the given date.
    Example: "2026-09-27T11:21:23"

## Response 200 fields (application/json):

  - `page` (object)
    Details the page that's returned.

  - `page.limit` (integer)
    The number of entries to return.

  - `page.next_cursor` (string,null)
    The cursor to use for the next page of results.

  - `_embedded` (object)

  - `_embedded.subscription_plans` (array)

  - `_embedded.subscription_plans.id` (string)
    The ID of the resource.

  - `_embedded.subscription_plans.created_at` (string)
    Timestamp of when the object was created.

  - `_embedded.subscription_plans.updated_at` (string)
    Timestamp of when the object was last updated.

  - `_embedded.subscription_plans.application_id` (string)
    ID of the Application the resource was created under.

  - `_embedded.subscription_plans.linked_to` (string)
    The ID of the [Merchant](#Merchants) resource that you wish to link to the Subscription Plan (i.e., the merchant that the subscription plan belongs to).

At this time, only approved merchants with one of the following processors are valid:

- DUMMY_V1
- FINIX_V1

  - `_embedded.subscription_plans.linked_type` (string)
    The type of the resource that is specified in the linked_to field.
    Enum: "MERCHANT"

  - `_embedded.subscription_plans.billing_interval` (string)
    How often the subscriber is billed.
    Enum: "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "YEARLY"

  - `_embedded.subscription_plans.nickname` (string)
    A human-readable name for the resource.

  - `_embedded.subscription_plans.plan_name` (string)
    A human-friendly name for the Subscription Plan.

  - `_embedded.subscription_plans.description` (string)
    A description of the Subscription Plan.

  - `_embedded.subscription_plans.amount` (integer)
    The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).
    Example: 5000

  - `_embedded.subscription_plans.currency` (string)
    ISO 4217 3-letter currency code.
    Enum: "USD", "CAD"

  - `_embedded.subscription_plans.default_total_billing_intervals` (integer,null)
    The total number of billing intervals for subscriptions created from this plan. This is the count of recurring billing cycles, with the interval unit defined by the plan’s billing_interval, such as weekly, monthly, etc. If included, the plan’s duration_type will be set to FIXED_TERM.

Subscriptions created with this plan will use the default duration in the total_billing_intervals field. The subscription's expires_at field will be set to the datetime when the subscription expires based on the plan's default_total_billing_intervals.

  - `_embedded.subscription_plans.duration_type` (string,null)
    Whether subscriptions created from this plan will have a fixed term or will continue until canceled. If default_total_billing_intervals is set, this plan's duration_type is automatically set to FIXED_TERM. Otherwise, the duration_type is set to EVERGREEN.
    Enum: "FIXED_TERM", "EVERGREEN"

  - `_embedded.subscription_plans.billing_defaults` (object)
    Object containing default billing settings.

  - `_embedded.subscription_plans.billing_defaults.collection_method` (string)
    The method by which subscription payments are collected. At this time, only BILL_AUTOMATICALLY is supported.
    Enum: "BILL_AUTOMATICALLY"

  - `_embedded.subscription_plans.billing_defaults.send_invoice` (boolean)
    This feature has yet to be implemented.

  - `_embedded.subscription_plans.billing_defaults.send_receipt` (boolean)
    This feature has yet to be implemented.

  - `_embedded.subscription_plans.trial_defaults` (object)
    Object containing default trial settings.

  - `_embedded.subscription_plans.trial_defaults.interval_type` (string)
    The unit of time for the trial period.
    Enum: "DAY", "WEEK", "MONTH", "YEAR"

  - `_embedded.subscription_plans.trial_defaults.interval_count` (integer)
    The number of intervals of interval_type used to describe the duration of the trial.

  - `_embedded.subscription_plans.discount_phase_defaults` (object)

  - `_embedded.subscription_plans.discount_phase_defaults.amount` (integer)
    The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).
    Example: 5000

  - `_embedded.subscription_plans.discount_phase_defaults.billing_interval_count` (integer)
    The number of billing intervals the discount applies. After this period, the subscriber is charged the full amount.

  - `_embedded.subscription_plans.state` (string)
    The state of the Subscription Plan.
    Enum: "ACTIVE", "INACTIVE"

  - `_embedded.subscription_plans.tags` (object,null)
    Include up to 50 key: value pairs to annotate requests with custom metadata.
- Maximum character length for individual keys is 40.
- Maximum character length for individual values is 500.
(For example, order_number: 25, item_type: produce, department: sales)

  - `_embedded.subscription_plans._links` (object)
    An object containing link(s) relevant to the request. You can store these links for follow-up requests.

  - `_embedded.subscription_plans._links.self` (object)
    Link to the resource that was used in the request.

  - `_embedded.subscription_plans._links.self.href` (string)

  - `_links` (object)

  - `_links.self` (object)
    Link to the resource that was used in the request.

  - `_links.self.href` (string)

  - `_links.next` (object)
    Link to the next page of entries.

  - `_links.next.href` (string)

## Response 401 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 403 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 406 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.