# List Subscriptions Retrieve a list of 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.lt` (integer) Filter by an amount less than. Example: 100 - `amount.lte` (integer) Filter by an amount less than or equal. 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 - `id` (string) Filter by . - `buyer_identity_id` (string) Filter by the Buyer Identity's ID. Example: "ID6Qm3BQUxGFcCWZ185TS8sn" - `linked_to` (string) Filter subscriptions linked to a specific . Example: "MUcgYZswyRfqSSbvMsxuaHxZ" - `state` (string) Filter by : - - - - - Example: "NOT_STARTED" - `subscription_plan_id` (string) Filter subscriptions that were created using a specific . Example: "subscription_plan_ciLn19pSKDTFoehtH7ET" - `limit` (integer) The numbers of items to return. Example: 3 - `created_at.gte` (string) Filter where is after the given date. Example: "2022-09-27T11:21:23" - `created_at.lte` (string) Filter where is before the given date. Example: "2026-09-27T11:21:23" - `updated_at.gte` (string) Filter where is after the given date. Example: "2022-09-27T11:21:23" - `updated_at.lte` (string) Filter where is before the given date. Example: "2026-09-27T11:21:23" - `before_cursor` (string) Return every resource created before the cursor value. - `after_cursor` (string) Return every resource created after the cursor value. ## 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) List of objects. - `_embedded.subscriptions` (array) objects. - `_embedded.subscriptions.id` (string) The ID of the resource. - `_embedded.subscriptions.created_at` (string) Timestamp of when the object was created. - `_embedded.subscriptions.updated_at` (string) Timestamp of when the object was last updated. - `_embedded.subscriptions.first_charge_at` (string) Timestamp when the first [](#Transfers) will occur. - `_embedded.subscriptions.amount` (integer) The total amount that will be debited in cents (e.g. 100 cents to debit $1.00). - `_embedded.subscriptions.buyer_details` (object) An object containing details about the subscriber. - `_embedded.subscriptions.buyer_details.identity_id` (string) The [identity ID](/api/identities) of the subscriber. - `_embedded.subscriptions.buyer_details.instrument_id` (any) The ID of the [](/api/payment-instruments) from which the subscription payments get debited. - `_embedded.subscriptions.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.subscriptions.buyer_details.requested_delivery_methods.type` (string, required) The method of receipt delivery. Enum: "EMAIL", "SMS", "PRINT" - `_embedded.subscriptions.buyer_details.requested_delivery_methods.destinations` (array, required) A list of destination addresses or identifiers where the receipt should be sent. - `_embedded.subscriptions.currency` (string) ISO 4217 3-letter currency code. Currently, the only supported is . Enum: "USD" - `_embedded.subscriptions.linked_to` (string) The ID of the [](#Merchants) resource that you wish to link to the (i.e., the merchant that the subscription belongs to). At this time, only approved merchants with one of the following processors are valid: - - - `_embedded.subscriptions.linked_type` (string) The type of the resource that is specified in the field. Enum: "MERCHANT" - `_embedded.subscriptions.nickname` (string) A human-readable name for the resource. Example: "super important thing" - `_embedded.subscriptions.billing_interval` (string) How often the subscriber is billed. Enum: "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "YEARLY" - `_embedded.subscriptions.subscription_plan_id` (string) The ID of the from which to create the . - `_embedded.subscriptions.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.subscriptions.subscription_details` (object) An object containing subscription details. - `_embedded.subscriptions.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.subscriptions.subscription_details.send_invoice` (boolean) Whether to send the user an invoice. - `_embedded.subscriptions.subscription_details.send_receipt` (boolean) Whether to send the user a receipt. - `_embedded.subscriptions.subscription_details.trial_details` (object) Object containing trial details. - `_embedded.subscriptions.subscription_details.trial_details.interval_type` (string) The unit of time for the trial period. Enum: "DAY", "WEEK", "MONTH", "YEAR" - `_embedded.subscriptions.subscription_details.trial_details.interval_count` (integer) The number of intervals of used to describe the duration of the trial. - `_embedded.subscriptions.subscription_details.trial_details.trial_started_at` (string) A timestamp indicating when the trial period began. - `_embedded.subscriptions.subscription_details.trial_details.trial_expected_end_at` (string) A timestamp indicating when the trial period ends. - `_embedded.subscriptions.subscription_details.discount_details` (object) Object containing discount details. - `_embedded.subscriptions.subscription_details.discount_details.interval_type` (string, required) The unit of time for the discount period. Enum: "DAY", "WEEK", "MONTH", "YEAR" - `_embedded.subscriptions.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 from the . - `_embedded.subscriptions.subscription_phase` (string) Indicates the period within a subscription where specific rules apply. - - The subscriber is billed continuously for the subscription until the subscription is canceled. - A state is applicable to fixed-length subscriptions. - - Indicates that when the timestamp is set during subscription creation, the subscription is not yet in any phase, and billing has not started. - - The period during which the subscriber is not billed; after this phase, the subscriber will begin being billed. Enum: "EVERGREEN", "FIXED", "NONE", "TRIAL" - `_embedded.subscriptions.state` (string) The state of the . - The state occurs when the subscription has not yet started, typically indicated by a timestamp set during creation. - A subscription in the state is unpaid but has not yet been canceled. Enum: "ACTIVE", "CANCELED", "EXPIRED", "NOT_STARTED", "PAST_DUE" - `_embedded.subscriptions.total_billing_intervals` (integer) The total number of billing intervals for the . This represents the total count of recurring billing cycles, such as months or weeks, depending on the billing frequency. - `_embedded.subscriptions.expires_at` (string) The date-time that the expires if is set for the . - `_embedded.subscriptions.tags` (object,null) Include up to 50 pairs to annotate requests with custom metadata. - Maximum character length for individual is 40. - Maximum character length for individual is 500. (For example, , , ) - `_embedded.subscriptions._links` (object) An object containing link(s) relevant to the request. You can store these links for follow-up requests. - `_embedded.subscriptions._links.self` (object) - `_embedded.subscriptions._links.self.href` (string) The path to the new resource. - `_links` (object) For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these to make your follow-up requests and quickly access relevant IDs. - `_links.next` (object) Link to the next page of entries. - `_links.next.href` (string) - `_links.self` (object) Link to the resource that was used in the request. ## Response 401 fields (application/json): - `total` (integer) - `_embedded` (object) - `_embedded.errors` (array) - `_embedded.errors.code` (string) Enum: "UNKNOWN" - `_embedded.errors.logref` (object) - `_embedded.errors.message` (string) - `_embedded.errors._links` (object) - `_embedded.errors._links.self` (object) - `_embedded.errors._links.self.href` (string) - `_embedded.errors._links.source` (object) ## Response 403 fields (application/json): - `total` (integer) - `_embedded` (object) - `_embedded.errors` (array) - `_embedded.errors.code` (string) Enum: "FORBIDDEN" - `_embedded.errors.logref` (object) - `_embedded.errors.message` (string) - `_embedded.errors._links` (object) - `_embedded.errors._links.source` (object) - `_embedded.errors._links.source.href` (string) ## Response 404 fields (application/json): - `total` (integer) - `_embedded` (object) - `_embedded.errors` (array) - `_embedded.errors.code` (string) Enum: "NOT_FOUND" - `_embedded.errors.logref` (object) - `_embedded.errors.message` (string) - `_embedded.errors._links` (object) - `_embedded.errors._links.source` (object) - `_embedded.errors._links.source.href` (string) ## Response 422 fields (application/json): - `total` (integer) - `_embedded` (object) - `_embedded.errors` (array) - `_embedded.errors.code` (string) Enum: "INVALID_FIELD" - `_embedded.errors.field` (string) - `_embedded.errors.logref` (object) - `_embedded.errors.message` (string) - `_embedded.errors._links` (object) - `_embedded.errors._links.source` (object) - `_embedded.errors._links.source.href` (string)