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

# Liste e filtre assinaturas

> Recupere uma lista paginada de assinaturas com filtros por status, e-mail, plano, bandeira do cartão e intervalo de data de criação.

export const SchemaLangNote = ({lang}) => {
  const text = ({
    es: "Los nombres de campos y el esquema de solicitud/respuesta que se muestran a continuación están en inglés — se generan a partir de la especificación OpenAPI. El texto explicativo de esta página está traducido.",
    pt: "Os nomes dos campos e o esquema de requisição/resposta exibidos abaixo estão em inglês — são gerados a partir da especificação OpenAPI. O texto explicativo desta página está traduzido."
  })[lang] || "Field names and the request/response schema shown below are in English — they are generated from the OpenAPI specification.";
  return <Note>{text}</Note>;
};

`GET /subscription` devolve uma lista paginada das suas assinaturas. Filtre por status, e-mail ou nome do cliente, plano, bandeira do cartão ou intervalo de data de criação para restringir os resultados. Os resultados são devolvidos em ordem cronológica inversa por data de criação.

<SchemaLangNote lang="pt" />

Filtre e pagine com os parâmetros de consulta do painel acima (`created_from`/`created_to` são limites de data ISO 8601 inclusivos sobre `createdAt`). Formato da resposta:

```json theme={"dark"}
{
  "data": [ ],
  "total": 142,
  "page": 1,
  "per_page": 20
}
```

<RequestExample>
  ```bash cURL theme={"dark"}
  curl "https://api.therius.io/v1/subscription?merchantCode=MERCHANT_001&status=active&per_page=50" \
    -H "Authorization: Bearer prv_production_your_key_here"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={"dark"}
  {}
  ```
</ResponseExample>

<Tip>
  Combine `created_from` e `created_to` com `status=past_due` para identificar os assinantes que ficaram inadimplentes dentro de uma janela específica — útil para campanhas de recuperação direcionadas.
</Tip>


## OpenAPI

````yaml GET /subscription
openapi: 3.1.0
info:
  title: Therius API
  description: REST API for payments, subscriptions, and billing plans.
  version: 1.0.0
servers:
  - url: https://api.therius.io/v1
    description: Production
  - url: https://api-sandbox.therius.io/v1
    description: Sandbox
security:
  - bearerAuth: []
paths:
  /subscription:
    get:
      tags:
        - Subscriptions
      summary: List and filter subscriptions
      operationId: listSubscriptions
      parameters:
        - name: merchantCode
          in: query
          required: true
          description: Your merchant account identifier.
          schema:
            type: string
        - name: status
          in: query
          description: >-
            Filter by status: `pending`, `trialing`, `active`, `past_due`,
            `suspended`, `cancelled`, `paused`, `completed`.
          schema:
            type: string
        - name: email
          in: query
          description: Partial, case-insensitive match on customer email.
          schema:
            type: string
        - name: customer_name
          in: query
          description: Partial, case-insensitive match on customer name.
          schema:
            type: string
        - name: plan_id
          in: query
          description: Filter to one plan ID.
          schema:
            type: string
        - name: card_brand
          in: query
          description: Filter by card brand, e.g. `visa`, `mastercard`, `amex`.
          schema:
            type: string
        - name: created_from
          in: query
          description: ISO 8601 date lower bound (inclusive) on creation date.
          schema:
            type: string
        - name: created_to
          in: query
          description: ISO 8601 date upper bound (inclusive) on creation date.
          schema:
            type: string
        - name: page
          in: query
          description: Page number, starting at 1. Default 1.
          schema:
            type: integer
        - name: per_page
          in: query
          description: Results per page. Default 20, max 200.
          schema:
            type: integer
      responses:
        '200':
          description: List of subscriptions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Subscription'
                  total:
                    type: integer
                    description: >-
                      Total subscriptions matching the filters, across all
                      pages.
                  page:
                    type: integer
                    description: Current page number.
                  per_page:
                    type: integer
                    description: Page size applied.
components:
  schemas:
    Subscription:
      type: object
      description: >-
        A customer enrollment in a plan. `plan` is embedded on
        single-subscription responses. Invoice/event history is not included
        here - use the invoice endpoints.
      properties:
        id:
          type: string
          description: Subscription UUID.
        merchantId:
          type: integer
          description: The merchant account that owns the subscription.
        planId:
          type: integer
          description: ID of the plan this subscription is enrolled in.
        customerEmail:
          type: string
          description: Subscriber email, used for billing and dunning notifications.
        customerName:
          type: string
          description: Subscriber name as it appears on invoices.
        customerDocument:
          type: string
          description: >-
            Subscriber national ID / tax document, where a market requires it
            (e.g. Brazil CPF/CNPJ).
        cardBrand:
          type: string
          description: Brand of the card on the mandate, e.g. `visa`.
        status:
          type: string
          enum:
            - pending
            - trialing
            - active
            - past_due
            - suspended
            - paused
            - cancelled
            - completed
          description: >-
            `pending` - awaiting first charge; `trialing` - in a free trial;
            `active` - billing normally; `past_due` - a renewal failed and
            dunning is running; `suspended` - dunning exhausted, needs a new CIT
            (`POST /subscription/{id}/payment-method` in CIT mode) to recover;
            `paused` - billing stopped on request, resumable; `cancelled` -
            terminated; `completed` - reached `maxBillingCycles`.
        currentPeriodStart:
          type: string
          format: date-time
          description: Start of the current billing period.
        currentPeriodEnd:
          type: string
          format: date-time
          description: End of the current billing period.
        nextBillingDate:
          type: string
          format: date-time
          description: When the next renewal charge is scheduled.
        trialStart:
          type: string
          format: date-time
          description: Trial start, when the plan has a trial.
        trialEnd:
          type: string
          format: date-time
          description: Trial end - the first real charge date.
        dunningAttemptCount:
          type: integer
          description: Failed-renewal retry attempts made in the current dunning sequence.
        activatedAt:
          type: string
          format: date-time
          description: When the subscription first became `active`.
        cancelledAt:
          type: string
          format: date-time
        pausedAt:
          type: string
          format: date-time
        suspendedAt:
          type: string
          format: date-time
        startAt:
          type: string
          format: date-time
          description: Deferred start, when creation set a future `startAt`.
        cyclesCompleted:
          type: integer
          description: Number of billing cycles charged so far.
        completedAt:
          type: string
          format: date-time
          description: When the subscription reached `maxBillingCycles`.
        parentSubscriptionId:
          type: string
          description: Parent subscription UUID, for add-on hierarchies.
        propagateLifecycle:
          type: boolean
          description: Whether pause/cancel on the parent cascades to this subscription.
        pendingPlanId:
          type: integer
          description: >-
            Plan the subscription will switch to at the next cycle, set by a
            `next_billing` change-plan.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        plan:
          $ref: '#/components/schemas/Plan'
    Plan:
      type: object
      description: >-
        A reusable billing plan. `amount` is a flat integer in the currency
        minor units (with separate `currency` + `exponent`) - not an Amount
        object.
      properties:
        id:
          type: integer
          description: The plan unique integer ID.
        merchantId:
          type: integer
          description: The merchant account that owns the plan.
        name:
          type: string
        description:
          type: string
        interval:
          type: string
          enum:
            - day
            - week
            - month
            - year
          description: Billing interval unit. Immutable after creation.
        intervalCount:
          type: integer
          description: >-
            Number of `interval` units between charges - `month` + `3` bills
            quarterly.
        amount:
          type: integer
          description: >-
            Recurring charge in the currency minor units (e.g. `2999` = $29.99
            at exponent 2). Immutable after creation.
        currency:
          type: string
          description: ISO 4217 currency code. Immutable after creation.
        exponent:
          type: integer
          description: >-
            Decimal places for `amount` / `introAmount` - `2` for USD, `0` for
            JPY.
        trialPeriodDays:
          type: integer
          description: Free-trial length in days before the first charge. `0` for no trial.
        introAmount:
          type: integer
          description: >-
            Introductory charge in minor units for the first
            `introBillingCycles` cycles, if set.
        introBillingCycles:
          type: integer
          description: >-
            How many initial cycles are billed at `introAmount` before the rate
            reverts to `amount`.
        maxBillingCycles:
          type: integer
          description: >-
            Total cycles after which the subscription auto-completes. `0` =
            open-ended.
        availableCountries:
          type: array
          items:
            type: string
          description: >-
            ISO 3166-1 alpha-2 codes the plan is offered in. Empty = available
            everywhere.
        isActive:
          type: boolean
          description: >-
            Whether the plan accepts new subscribers. Existing subscriptions are
            unaffected when this is `false`.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your secret API key: `Bearer prv_production_xxx` (production) or `Bearer
        prv_sandbox_xxx` (sandbox).

````