# List Subscription Links

Retrieve a list of Subscription Link resources.

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

## Query parameters:

  - `is_multiple_use` (boolean)
    Filter the list to multiple or single-use links.
    Example: true

  - `state` (string)
    Filter by the current state of the Subscription Link.
    Enum: "ACTIVE", "DEACTIVATED", "EXPIRED", "COMPLETED"

  - `subscription_plan_id` (string)
    Filter links created using a specific Subscription Plan.
    Example: "subscription_plan_cmsyQKfkpSEtUVfvxr9Dc"

  - `type` (string)
    Filter by the type of Subscription Link.
    Enum: "SUBSCRIPTION_PLAN", "MULTIPLE_SUBSCRIPTION_PLANS"

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

  - `id` (string)
    Filter by id.

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

## Header parameters:

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

## Response 200 fields (application/json):

  - `_embedded` (object)

  - `_embedded.subscription_links` (array)

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

  - `_embedded.subscription_links.additional_details` (object)
    Object containing additional details about the link.

  - `_embedded.subscription_links.additional_details.collect_name` (boolean)
    The collected user's name.

  - `_embedded.subscription_links.additional_details.collect_email` (boolean)
    The collected email address.

  - `_embedded.subscription_links.additional_details.collect_phone` (boolean)
    The collected phone number.

  - `_embedded.subscription_links.additional_details.collect_shipping_address` (boolean)
    The collected shipping address.

  - `_embedded.subscription_links.additional_details.expiration_in_minutes` (string)
    How long (in minutes) the link should be valid for. Defaults to 60 minutes.

  - `_embedded.subscription_links.additional_details.expired_session_url` (string)
    The URL to redirect the user to if the link expires.

  - `_embedded.subscription_links.additional_details.receipt_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_links.additional_details.receipt_requested_delivery_methods.type` (string, required)
    The method of receipt delivery.
    Enum: "EMAIL", "SMS", "PRINT"

  - `_embedded.subscription_links.additional_details.receipt_requested_delivery_methods.destinations` (array, required)
    A list of destination addresses or identifiers where the receipt should be sent.

  - `_embedded.subscription_links.additional_details.send_confirmation` (boolean)
    Setting this flag to true validates the provided email address and sends a confirmation email to that address. When set to true, the collect_email field must include an email. When set to false (default), no confirmation email will be sent (e.g., the merchant does not require it.)

  - `_embedded.subscription_links.additional_details.send_receipt` (boolean)
    Whether to send the user a Receipt.

  - `_embedded.subscription_links.additional_details.success_return_url` (string,null)
    A URL to redirect the subscriber after the transaction completes.

  - `_embedded.subscription_links.additional_details.terms_of_service_url` (string,null)
    The URL to the Terms of Service.

  - `_embedded.subscription_links.additional_details.unsuccessful_return_url` (string,null)
    A URL to redirect the user to if the transaction was successful.

  - `_embedded.subscription_links.allowed_payment_methods` (array)
    The allowed payment methods.
    Enum: "APPLE_PAY", "BANK_ACCOUNT", "GOOGLE_PAY", "PAYMENT_CARD"

  - `_embedded.subscription_links.application_id` (string)
    The ID of the Application the Subscription Link was created under.

  - `_embedded.subscription_links.branding` (object)
    Branding settings for the Subscription Link.

  - `_embedded.subscription_links.branding.accent_color` (string, required)
    Hex code of the accent color.
    Example: "#F2F2F2"

  - `_embedded.subscription_links.branding.brand_color` (string, required)
    Hex code of branding color.
    Example: "#F2F2F2"

  - `_embedded.subscription_links.branding.button_font_color` (string,null)
    Hex code of the button font color.

  - `_embedded.subscription_links.branding.icon` (string, required)
    URL for the icon of the payment link.

  - `_embedded.subscription_links.branding.logo` (string, required)
    URL of the logo for the payment link.

  - `_embedded.subscription_links.branding.logo_alternative_text` (string,null)
    Alternate text displayed if the logo image cannot display.

  - `_embedded.subscription_links.branding.button_label` (string)
    The text that displays within the button.

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

  - `_embedded.subscription_links.is_multiple_use` (boolean)
    If set to true, the link can be used more than once.

  - `_embedded.subscription_links.link_expires_at` (string)
    Timestamp of when the link will expire.

  - `_embedded.subscription_links.link_url` (string)
    The URL of the link.

  - `_embedded.subscription_links.merchant_id` (string)
    The Merchant asssociated with the link.

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

  - `_embedded.subscription_links.plans` (array)
    A list of Subscription Plan objects, along with additional information for each plan if selected.

  - `_embedded.subscription_links.plans.subscription_plan_id` (string)
    The Subscription Plan that a customer selects via the Subscription Link.

  - `_embedded.subscription_links.plans.name` (string)
    The name of the Subscription Plan you wish to display to your buyer. This may differ from the internal nickname of the Subscription Plan.

  - `_embedded.subscription_links.plans.image_details` (object)
    Subscription Link image locations.

  - `_embedded.subscription_links.plans.image_details.primary_image_url` (string)
    The primary image location.

  - `_embedded.subscription_links.plans.image_details.alternative_image_urls` (array)
    The locations of backup images if there is an issue with the primary image.

  - `_embedded.subscription_links.plans.url_details` (object)

  - `_embedded.subscription_links.plans.url_details.success_return_url` (string)
    The URL to redirect the user after the transaction completes.

  - `_embedded.subscription_links.plans.url_details.unsuccessful_return_url` (string)
    If an attempt is made but fails, redirect the user to this URL.

  - `_embedded.subscription_links.plans.url_details.expired_session_url` (string)
    The URL to redirect the user to if their session times out.

  - `_embedded.subscription_links.plans.url_details.terms_of_service_url` (string)
    A Terms of Service URL.

  - `_embedded.subscription_links.state` (string)
    The current state of the Subscription Link.
    Enum: "ACTIVE", "DEACTIVATED", "EXPIRED", "COMPLETED"

  - `_embedded.subscription_links.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.type` (string)
    The type of Subscription Link. This is very useful for filtering and informing the frontend about the type of Subscription Link.
    Enum: "SUBSCRIPTION_PLAN", "MULTIPLE_SUBSCRIPTION_PLANS"

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

  - `_embedded.subscription_links._links` (object)

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

  - `_embedded.subscription_links._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)

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

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