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

# Search and filter subscriptions

> Return subscriptions list with filters and pagination.



## OpenAPI

````yaml /swagger/openapi-billing.json post /subscription/search
openapi: 3.0.0
info:
  title: OpenAPI3
  version: 1.0.0
servers:
  - url: https://billing.funnelfox.com/{org_id}/v1
    description: FunnelFox Billing API
    variables:
      org_id:
        default: your-org-id
        description: Your organization ID
security:
  - FunnelFoxSecretKey: []
paths:
  /subscription/search:
    post:
      tags:
        - Subscription management
      summary: Search and filter subscriptions
      description: Return subscriptions list with filters and pagination.
      parameters:
        - name: org_id
          in: path
          required: true
          description: Organization ID
          schema:
            type: string
          style: simple
          explode: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterSubscriptionIn'
      responses:
        '200':
          description: List of subscriptions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionListOut'
components:
  schemas:
    FilterSubscriptionIn:
      properties:
        external_id:
          maxLength: 256
          type: string
          nullable: true
        intro_type:
          anyOf:
            - $ref: '#/components/schemas/IntroTypeEnum'
          default: null
          nullable: true
        subs_id:
          format: uuid
          type: string
          nullable: true
        status_eq:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          nullable: true
        status_consists:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          nullable: true
        created_at_from:
          format: date-time
          type: string
          nullable: true
        created_at_to:
          format: date-time
          type: string
          nullable: true
        order_by:
          $ref: '#/components/schemas/SubsOrderBy'
          default: started_at
        sort_direction:
          $ref: '#/components/schemas/SortDirection'
          default: desc
        limit:
          default: 100
          maximum: 500
          minimum: 0
          title: Limit
          type: integer
        page:
          default: 1
          minimum: 0
          title: Page
          type: integer
        next_check_from:
          format: date-time
          type: string
          nullable: true
        next_check_to:
          format: date-time
          type: string
          nullable: true
      title: FilterSubscriptionIn
      type: object
    SubscriptionListOut:
      properties:
        subscriptions:
          items:
            $ref: '#/components/schemas/SubscriptionOut'
          title: Subscriptions
          type: array
      required:
        - subscriptions
      title: SubscriptionListOut
      type: object
    IntroTypeEnum:
      enum:
        - no_intro
        - free_trial
        - paid_trial
      title: IntroTypeEnum
      type: string
    SubsOrderBy:
      enum:
        - started_at
        - next_check
      title: SubsOrderBy
      type: string
    SortDirection:
      enum:
        - asc
        - desc
      title: SortDirection
      type: string
    SubscriptionOut:
      properties:
        subs_id:
          format: uuid
          title: Subs Id
          type: string
        is_active:
          description: Whether premium features are currently available
          title: Is Active
          type: boolean
        price_point:
          $ref: '#/components/schemas/PricePointOut'
        status:
          description: Current subscription status flags
          items:
            type: string
          title: Status
          type: array
        started_at:
          description: When the subscription first started
          format: date-time
          title: Started At
          type: string
        current_period_starts_at:
          description: Start of the current billing period (may be in the future)
          format: date-time
          title: Current Period Starts At
          type: string
        current_period_ends_at:
          description: >-
            End of the current billing period (may be in the past if payment
            failed)
          format: date-time
          title: Current Period Ends At
          type: string
        next_check_at:
          format: date-time
          type: string
          nullable: true
        next_payment_at:
          format: date-time
          type: string
          nullable: true
        iteration:
          description: Cycle iteratin
          title: Iteration
          type: integer
        available_actions:
          description: Actions available for this subscription
          items:
            $ref: '#/components/schemas/SubsAwailableActions'
          title: Available Actions
          type: array
        initial_order_metadata:
          additionalProperties: true
          description: Metadata from the initial order that created this subscription
          title: Initial Order Metadata
          type: object
        discounts:
          description: Discount
          items:
            $ref: '#/components/schemas/DiscountOut'
          title: Discounts
          type: array
        unused_premium_after_pause:
          type: integer
          nullable: true
      required:
        - subs_id
        - is_active
        - price_point
        - status
        - started_at
        - current_period_starts_at
        - current_period_ends_at
        - next_check_at
        - iteration
        - available_actions
        - initial_order_metadata
        - discounts
      title: SubscriptionOut
      type: object
    PricePointOut:
      properties:
        ident:
          title: Ident
          type: string
        currency:
          $ref: '#/components/schemas/CurrencyOut'
        intro_type:
          $ref: '#/components/schemas/IntroTypeEnum'
        lifetime_price:
          anyOf:
            - type: number
            - type: string
          default: null
          title: Lifetime Price
          nullable: true
        intro_free_trial_period:
          type: integer
          nullable: true
        intro_free_trial_period_duration:
          anyOf:
            - $ref: '#/components/schemas/DurationEnum'
          default: null
          nullable: true
        intro_paid_trial_price:
          anyOf:
            - type: number
            - type: string
          default: null
          title: Intro Paid Trial Price
          nullable: true
        intro_paid_trial_period:
          type: integer
          nullable: true
        intro_paid_trial_period_duration:
          anyOf:
            - $ref: '#/components/schemas/DurationEnum'
          default: null
          nullable: true
        next_price:
          anyOf:
            - type: number
            - type: string
          default: null
          title: Next Price
          nullable: true
        next_period:
          type: integer
          nullable: true
        next_period_duration:
          anyOf:
            - $ref: '#/components/schemas/DurationEnum'
          default: null
          nullable: true
        features:
          description: Premium features included in this price point
          items:
            $ref: '#/components/schemas/FeatureOut'
          title: Features
          type: array
      required:
        - ident
        - currency
        - intro_type
        - features
      title: PricePointOut
      type: object
    SubsAwailableActions:
      enum:
        - pause
        - resume
        - defer
        - disable_autorenew
        - enable_autorenew
        - create_discount
        - migration
      title: SubsAwailableActions
      type: string
    DiscountOut:
      properties:
        discount_id:
          format: uuid
          title: Discount Id
          type: string
        subs_id:
          format: uuid
          title: Subs Id
          type: string
        count_of_iterations:
          type: integer
          nullable: true
        count_of_iterations_available:
          type: integer
          nullable: true
        percent:
          type: integer
          nullable: true
        report:
          additionalProperties:
            type: string
          title: Report
          type: object
      required:
        - discount_id
        - subs_id
        - count_of_iterations
        - count_of_iterations_available
        - percent
        - report
      title: DiscountOut
      type: object
    CurrencyOut:
      properties:
        code:
          title: Code
          type: string
        minor_units:
          title: Minor Units
          type: integer
        title:
          title: Title
          type: string
        symbol:
          title: Symbol
          type: string
      required:
        - code
        - minor_units
        - title
        - symbol
      title: CurrencyOut
      type: object
    DurationEnum:
      enum:
        - minutes
        - days
        - weeks
        - months
        - years
      title: DurationEnum
      type: string
    FeatureOut:
      properties:
        ident:
          title: Ident
          type: string
      required:
        - ident
      title: FeatureOut
      type: object
  securitySchemes:
    FunnelFoxSecretKey:
      type: apiKey
      in: header
      name: ff-secret-key
      description: Secret key for FunnelFox Billing API. Required for all requests.

````