# List Subscriptions

Retrieve a list of Subscription resources. 

For details on how to query endpoints using the available parameters, see Query Parameters.

Endpoint: GET /subscriptions
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` (integer)
    Filter by an amount equal to the given value.
    Example: 100

  - `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

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

  - `buyer_identity_id` (string)
    Filter by the Buyer Identity's ID.
    Example: "ID6Qm3BQUxGFcCWZ185TS8sn"

  - `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"

  - `id` (string)
    Filter by id.

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

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

  - `state` (string)
    Filter by state:
- ACTIVE
- CANCELED
- EXPIRED
- NOT_STARTED
- PAST DUE
    Example: "NOT_STARTED"

  - `subscription_link_id` (string)
    Filter subscriptions created by a Subscription Link.
    Example: "subscription_link_cvTp2K5CNH9Lr4BqCphcM"

  - `subscription_plan_id` (string)
    Filter subscriptions that were created using a specific Subscription Plan.
    Example: "subscription_plan_ciLn19pSKDTFoehtH7ET"

  - `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` (array)

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

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

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

  - `_embedded.Subscription.first_charge_at` (string)
    Timestamp when the first [Transfer](#Transfers) will occur.

  - `_embedded.Subscription.next_billing_date` (object)
    Details when the next [Transfer](#Transfers) will occur.

  - `_embedded.Subscription.next_billing_date.year` (integer)
    The year the next Transfer will occur.

  - `_embedded.Subscription.next_billing_date.month` (integer)
    The month the next Transfer will occur.

  - `_embedded.Subscription.next_billing_date.day` (integer)
    The day the next Transfer will occur.

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

  - `_embedded.Subscription.buyer_details` (object)
    An object containing details about the subscriber.

  - `_embedded.Subscription.buyer_details.identity_id` (string)
    The [identity ID](/api/identities) of the subscriber.

  - `_embedded.Subscription.buyer_details.instrument_id` (any)
    The ID of the [Payment Instrument](/api/payment-instruments) from which the subscription payments get debited.

  - `_embedded.Subscription.buyer_details.requested_delivery_methods` (array)
    A list of requested delivery methods. Each method specifies 
the type of delivery and the destination(s) where the receipt should be sent.

  - `_embedded.Subscription.buyer_details.requested_delivery_methods.type` (string, required)
    The method of receipt delivery.
    Enum: "EMAIL", "SMS", "PRINT"

  - `_embedded.Subscription.buyer_details.requested_delivery_methods.destinations` (array, required)
    A list of destination addresses or identifiers where the receipt should be sent.

  - `_embedded.Subscription.buyer_details.shipping_address` (object,null)

  - `_embedded.Subscription.buyer_details.shipping_address.line1` (string,null, required)
    First line of the address (max 35 characters).

  - `_embedded.Subscription.buyer_details.shipping_address.line2` (string,null)
    Second line of the address (max 35 characters).

  - `_embedded.Subscription.buyer_details.shipping_address.city` (string,null, required)
    City (max 20 characters).

  - `_embedded.Subscription.buyer_details.shipping_address.region` (string,null, required)
    2-letter State code.

  - `_embedded.Subscription.buyer_details.shipping_address.postal_code` (string,null, required)
    Zip or Postal code (max 7 characters).

  - `_embedded.Subscription.buyer_details.shipping_address.country` (string,null, required)
    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"

  - `_embedded.Subscription.currency` (string)
    ISO 4217 3-letter currency code. Currently, the only currency supported is USD.
    Enum: "USD"

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

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

- DUMMY_V1
- FINIX_V1

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

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

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

  - `_embedded.Subscription.subscription_details` (object)
    An object containing subscription details.

  - `_embedded.Subscription.subscription_details.collection_method` (string, required)
    The method by which subscription payments are collected. Currently, automatically billing the card on file is the only method available.
    Enum: "BILL_AUTOMATICALLY"

  - `_embedded.Subscription.subscription_details.send_invoice` (boolean)
    Whether to send the user an invoice.

  - `_embedded.Subscription.subscription_details.send_receipt` (boolean)
    Whether to send the user a receipt.

  - `_embedded.Subscription.subscription_details.trial_details` (object)
    Object containing trial details.

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

  - `_embedded.Subscription.subscription_details.trial_details.interval_count` (integer)
    The number of intervals of interval_type used to describe the duration of the trial.

  - `_embedded.Subscription.subscription_details.trial_details.trial_started_at` (string)
    A timestamp indicating when the trial period began.

  - `_embedded.Subscription.subscription_details.trial_details.trial_expected_end_at` (string)
    A timestamp indicating when the trial period ends.

  - `_embedded.Subscription.subscription_details.discount_details` (object)
    Object containing discount details.

  - `_embedded.Subscription.subscription_details.discount_details.interval_type` (string, required)
    The unit of time for the discount period.
    Enum: "DAY", "WEEK", "MONTH", "YEAR"

  - `_embedded.Subscription.subscription_details.discount_details.billing_interval_count` (integer, required)
    The number of billing intervals the discount applies. After this period, the subscriber is charged the full amount from the Subscription.

  - `_embedded.Subscription.subscription_details.notification_preferences` (object)
    Object containing notification preferences.

  - `_embedded.Subscription.subscription_details.notification_preferences.send_confirmation` (boolean)
    Whether to send a confirmation email to the user.

  - `_embedded.Subscription.subscription_link_id` (string,null)
    The ID of the Subscription Link that created the Subscription.

  - `_embedded.Subscription.subscription_phase` (string)
    Indicates the period within a subscription where specific rules apply.  

- EVERGREEN - The subscriber is billed continuously for the subscription until the subscription is canceled.  
- DISCOUNT - The subscriber receives a discounted price for a limited billing interval, after which the customer is charged the full subscription amount.
- FIXED state - Applicable to fixed-length subscriptions.
- 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.
- TRIAL - The period during which the subscriber is not billed; after this phase, the subscriber will begin being billed.
    Enum: "EVERGREEN", "DISCOUNT", "FIXED", "NONE", "TRIAL"

  - `_embedded.Subscription.state` (string)
    The state of the Subscription. 

- The NOT_STARTED state occurs when the subscription has not yet started, typically indicated by a start_subscription_at timestamp set during creation.
- A subscription in the PAST_DUE state is unpaid but has not yet been canceled.
    Enum: "ACTIVE", "CANCELED", "EXPIRED", "NOT_STARTED", "PAST_DUE"

  - `_embedded.Subscription.subscription_plan_id` (string)
    The ID of the Subscription Plan from which to create the Subscription.

  - `_embedded.Subscription.start_subscription_at` (string)
    Indicates that the subscription is scheduled to begin in the future. The timestamp specifies the exact start date for subscription billing.

  - `_embedded.Subscription.total_billing_intervals` (integer)
    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.

  - `_embedded.Subscription.expires_at` (string)
    The date-time that the Subscription expires if total_billing_intervals is set for the Subscription.

  - `_embedded.Subscription.canceled_via` (string)
    If the subscription was canceled, this field shows how the cancellation was initiated.

Possible values:

- MERCHANT - The customer (merchant) canceled the subscription themselves. The linked_to field indicates the related Merchant.
- AUTOMATED_OVERDUE - The subscription was canceled by the overdue system.
- SUPPORT - The subscription was canceled by Finix Support.
    Enum: "MERCHANT", "AUTOMATED_OVERDUE", "SUPPORT"

  - `_embedded.Subscription.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._links` (object)
    An object containing link(s) relevant to the request. You can store these links for follow-up requests.

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

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

  - `_links` (object)

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

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