> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tagada.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List subscriptions

> Get all subscriptions for the authenticated account with filtering, sorting, and pagination



## OpenAPI

````yaml /openapi.json post /api/public/v1/subscriptions/list
openapi: 3.0.3
info:
  title: TagadaPay API
  description: >-

    # TagadaPay API Documentation


    Welcome to the TagadaPay API. This REST API lets you process payments,
    manage subscriptions, handle customers, deploy plugins, and orchestrate
    checkout funnels — all programmatically.


    ## Authentication


    Authenticate every request with a Bearer token. Get your API key from the
    [TagadaPay Dashboard](https://app.tagada.io).


    ```

    Authorization: Bearer your-api-key

    ```


    All requests must be made over HTTPS with `Content-Type: application/json`.


    ## Rate Limits


    | Plan | Requests/min | Burst |

    |------|-------------|-------|

    | Standard | 100 | 150 |

    | Premium | 500 | 750 |


    Exceeding the limit returns `429 Too Many Requests`.


    ## Errors


    | Code | Meaning |

    |------|---------|

    | 400 | Bad request — invalid parameters |

    | 401 | Unauthorized — missing or invalid API key |

    | 403 | Forbidden — insufficient permissions |

    | 404 | Not found |

    | 409 | Conflict |

    | 429 | Rate limited |

    | 500 | Server error |


    ## Support


    - Email: api-support@tagada.io

    - Docs: [docs.tagadapay.com](https://docs.tagadapay.com)
        
  version: 1.0.0
servers:
  - url: https://api.tagada.io/
    description: Production
  - url: https://api.tagada.dev/
    description: Sandbox / Development
security:
  - bearerAuth: []
tags:
  - name: auth
    description: Test your API key and verify authentication.
  - name: stores
    description: Create and manage stores within your account.
  - name: products
    description: Create products with variants, prices, and currency options.
  - name: customers
    description: Manage customer records, addresses, and payment instruments.
  - name: orders
    description: List and retrieve orders with line items, payments, and metadata.
  - name: payments
    description: Process, list, refund, void, and dispute payments.
  - name: subscriptions
    description: >-
      Create and manage recurring subscriptions — billing, cancellation,
      rebilling, and processor changes.
  - name: payment-flows
    description: Configure payment routing strategies with cascading processor fallbacks.
  - name: payment-instruments
    description: >-
      Manage stored payment methods — cards, bank accounts, and tokenized
      instruments.
  - name: processors
    description: List connected payment processors (Stripe, NMI, Checkout.com, etc.).
  - name: promotions
    description: Create and manage discount promotions with rules and conditions.
  - name: promotion-codes
    description: Generate and manage reusable promotion/coupon codes.
  - name: block-rules
    description: >-
      Configure fraud prevention rules to block transactions by IP, email, card
      BIN, country, etc.
  - name: webhooks
    description: Register webhook endpoints to receive real-time event notifications.
  - name: events
    description: Query application events, statistics, and audit logs.
  - name: domains
    description: Add, verify, and manage custom domains for your checkout and funnels.
  - name: funnels
    description: >-
      Create and manage checkout funnels with routing, A/B testing, and CDN
      deployment.
  - name: funnel-sessions
    description: Retrieve funnel session data for analytics and debugging.
  - name: funnel-tracking
    description: Track funnel step events for conversion analytics.
  - name: plugins
    description: Deploy, manage, and configure checkout plugins.
  - name: plugins-v2
    description: >-
      V2 plugin system — deploy, mount, split-test, fork, promote, and manage
      plugin instances.
  - name: checkout
    description: >-
      Initialize checkout sessions and process payments through the hosted
      checkout.
  - name: 3ds
    description: >-
      3D Secure authentication — create sessions, authenticate, and handle
      challenges.
  - name: builder
    description: Generate and validate builder session tokens for the visual page editor.
  - name: health
    description: API health check endpoint.
  - name: test
    description: Test and debugging utilities for the event system (sandbox only).
paths:
  /api/public/v1/subscriptions/list:
    post:
      tags:
        - subscriptions
      summary: List subscriptions
      description: >-
        Get all subscriptions for the authenticated account with filtering,
        sorting, and pagination
      operationId: post-api-public-v1-subscriptions-list
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                page:
                  type: integer
                  minimum: 1
                  default: 1
                  nullable: true
                per_page:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 20
                  nullable: true
                search:
                  type: string
                sort:
                  type: string
                  enum:
                    - customers.email
                    - customers.fullName
                    - subscriptions.status
                    - subscriptions.price
                    - subscriptions.createdAt
                    - subscriptions.billing_period
                    - subscriptions.nextBillingDate
                    - subscriptions.processorName
                    - paymentType
                  default: subscriptions.createdAt
                  nullable: true
                sort_order:
                  type: string
                  enum:
                    - asc
                    - desc
                  default: desc
                  nullable: true
                filters:
                  type: object
                  properties:
                    paymentType:
                      type: array
                      items:
                        type: string
                    storeIds:
                      type: array
                      items:
                        type: string
                        minLength: 1
                    processorIds:
                      type: array
                      items:
                        type: string
                        minLength: 1
                    subscriptions.status:
                      type: array
                      items:
                        type: string
                    subscriptions.trial:
                      type: string
                      enum:
                        - trial
                        - active
                        - all
                    currency:
                      type: array
                      items:
                        type: string
                    price:
                      anyOf:
                        - type: object
                          properties:
                            equals:
                              type: number
                          required:
                            - equals
                          additionalProperties: false
                        - type: object
                          properties:
                            isBetween:
                              type: object
                              properties:
                                min:
                                  type: number
                                max:
                                  type: number
                              required:
                                - min
                                - max
                              additionalProperties: false
                          required:
                            - isBetween
                          additionalProperties: false
                        - type: object
                          properties:
                            isGreaterThan:
                              type: number
                          required:
                            - isGreaterThan
                          additionalProperties: false
                        - type: object
                          properties:
                            isLessThan:
                              type: number
                          required:
                            - isLessThan
                          additionalProperties: false
                    customerEmail:
                      type: object
                      properties:
                        condition:
                          type: string
                          enum:
                            - contains
                        value:
                          type: string
                      required:
                        - condition
                        - value
                      additionalProperties: false
                    date:
                      type: object
                      properties:
                        condition:
                          type: string
                          enum:
                            - is-equal-date
                            - is-between-date
                            - is-after-date
                            - is-before-date
                        value:
                          type: array
                          items:
                            type: string
                      required:
                        - condition
                        - value
                      additionalProperties: false
                    nextBillingDate:
                      type: object
                      properties:
                        condition:
                          type: string
                          enum:
                            - is-equal-date
                            - is-between-date
                            - is-after-date
                            - is-before-date
                        value:
                          type: array
                          items:
                            type: string
                      required:
                        - condition
                        - value
                      additionalProperties: false
                  additionalProperties: false
              additionalProperties: false
            examples:
              basic:
                summary: Basic subscription list
                value:
                  page: 1
                  per_page: 20
              filtered:
                summary: Filtered subscriptions
                value:
                  page: 1
                  per_page: 50
                  sort: subscriptions.createdAt
                  sort_order: desc
                  filters:
                    subscriptions.status:
                      - active
                      - trialing
                    subscriptions.trial: active
                    currency:
                      - USD
                    customerEmail:
                      condition: contains
                      value: john@example.com
                    price:
                      isBetween:
                        min: 999
                        max: 9999
                    date:
                      condition: is-after-date
                      value:
                        - '2024-01-01'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        status:
                          type: string
                        storeId:
                          type: string
                          nullable: true
                        storeName:
                          type: string
                          nullable: true
                        createdAt:
                          type: string
                          format: date-time
                          nullable: true
                        currentPeriodStart:
                          type: string
                          format: date-time
                          nullable: true
                        currentPeriodEnd:
                          type: string
                          format: date-time
                          nullable: true
                        currency:
                          type: string
                        quantity:
                          type: number
                          nullable: true
                        trialEnd:
                          type: string
                          format: date-time
                          nullable: true
                        cancelAtPeriodEnd:
                          type: boolean
                          nullable: true
                        nextBillingDate:
                          type: string
                          format: date-time
                          nullable: true
                        customer:
                          type: string
                          nullable: true
                        customerId:
                          type: string
                          nullable: true
                        customerEmail:
                          type: string
                          nullable: true
                        priceCurrencyOptions:
                          type: object
                          additionalProperties:
                            type: object
                            properties:
                              rate:
                                type: number
                              amount:
                                type: number
                              lock:
                                type: boolean
                              date:
                                type: string
                            required:
                              - amount
                            additionalProperties: false
                          nullable: true
                        priceSettings:
                          nullable: true
                        sortableAmount:
                          type: number
                          nullable: true
                        useTagadaVault:
                          type: boolean
                          nullable: true
                        processorName:
                          type: string
                          nullable: true
                        processorId:
                          type: string
                          nullable: true
                        orderId:
                          type: string
                          nullable: true
                        paymentId:
                          type: string
                          nullable: true
                        paymentType:
                          type: string
                          nullable: true
                      required:
                        - id
                        - status
                        - storeId
                        - storeName
                        - createdAt
                        - currentPeriodStart
                        - currentPeriodEnd
                        - currency
                        - quantity
                        - trialEnd
                        - cancelAtPeriodEnd
                        - nextBillingDate
                        - customer
                        - customerId
                        - customerEmail
                        - priceCurrencyOptions
                        - sortableAmount
                        - useTagadaVault
                        - processorName
                        - processorId
                        - orderId
                        - paymentId
                        - paymentType
                      additionalProperties: false
                  pagination:
                    type: object
                    properties:
                      hasNext:
                        type: boolean
                      totalItems:
                        type: integer
                      nextPage:
                        type: integer
                        nullable: true
                      previousPage:
                        type: integer
                        nullable: true
                    required:
                      - hasNext
                      - totalItems
                      - nextPage
                      - previousPage
                    additionalProperties: false
                required:
                  - items
                  - pagination
                additionalProperties: false
              examples:
                success:
                  summary: Successful response
                  value:
                    items:
                      - id: sub_123
                        status: active
                        createdAt: '2024-03-20T10:30:00Z'
                        currency: USD
                        customer: John Doe
                        customerEmail: john@example.com
                        priceCurrencyOptions:
                          USD:
                            amount: 2999
                          EUR:
                            amount: 2599
                        priceInterval: month
                        priceIntervalCount: 1
                        currentPeriodStart: '2024-03-20T00:00:00Z'
                        currentPeriodEnd: '2024-04-20T00:00:00Z'
                    pagination:
                      hasNext: false
                      totalItems: 1
                      nextPage: null
                      previousPage: null
        default:
          $ref: '#/components/responses/error'
      security:
        - bearerAuth: []
components:
  responses:
    error:
      description: Error response
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
              code:
                type: string
              issues:
                type: array
                items:
                  type: object
                  properties:
                    message:
                      type: string
                  required:
                    - message
                  additionalProperties: false
            required:
              - message
              - code
            additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Enter your API key as: `Bearer your-api-key`'

````