---
title: "List subscriptions"
description: "Paginated."
canonical_url: "https://twominutebilling.com/help/developers/api-reference/subscriptions/list-subscriptions"
---
# List subscriptions

> Paginated.

<api-operation method="GET" path="/v1/businesses/{biz}/subscriptions">
<template v-slot:docs="">

Cursor-paginated. `?customer=cus_a` scopes to one customer; `?customer=cus_a,cus_b` to a set. That shorthand is described here rather than listed as a parameter because it shares its name with the `customer` filter below, and a parameter name may only be declared once; `?customer[is]=cus_a` works too.

The business's own CUSTOM FIELDS filter through the same grammar but cannot be listed below: they are defined per business, so `?cf_<api_name>[<op>]=<value>` (e.g. `?cf_plan_tier[is]=gold`) is resolved per request from that business's definitions. Read them from `GET /v1/businesses/{biz}/custom_fields`.

## Path parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        biz
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      Business id (biz_…)
    </td>
  </tr>
</tbody>
</table>

## Query parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        limit
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Maximum number of subscriptions to return.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        starting_after
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Opaque cursor from a previous next_cursor
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        offset
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The previous page's next_offset — the same token as next_cursor under a second name. Pass one of offset or starting_after, not two different values.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        include_deleted
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Also list deleted subscriptions (hidden by default); each carries <code>
        deleted: true
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        q
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Free-text over subscription id / status / customer id, any name column (name, first/last, company), email
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sort_by[asc]
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Sort ascending by this field.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sort_by[desc]
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Sort descending by this field.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        id
      </code>
      
      . Send as <code>
        id[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        status
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        status
      </code>
      
      . Send as <code>
        status[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        currency
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        currency
      </code>
      
      . Send as <code>
        currency[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        start_date
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        start_date
      </code>
      
      . Send as <code>
        start_date[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        started_at
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        started_at
      </code>
      
      . Send as <code>
        started_at[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        activated_at
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        activated_at
      </code>
      
      . Send as <code>
        activated_at[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        trial_start
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        trial_start
      </code>
      
      . Send as <code>
        trial_start[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        trial_end
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        trial_end
      </code>
      
      . Send as <code>
        trial_end[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        current_period_start
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        current_period_start
      </code>
      
      . Send as <code>
        current_period_start[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        current_period_end
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        current_period_end
      </code>
      
      . Send as <code>
        current_period_end[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        next_billing_at
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        next_billing_at
      </code>
      
      . Send as <code>
        next_billing_at[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cancel_at_period_end
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        cancel_at_period_end
      </code>
      
      . Send as <code>
        cancel_at_period_end[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cancel_scheduled_at
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Set only while a specific_date cancellation is pending, so this answers "what cancels before X" rather than "what has cancelled".
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        canceled_at
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        canceled_at
      </code>
      
      . Send as <code>
        canceled_at[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cancel_reason
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        cancel_reason
      </code>
      
      . Send as <code>
        cancel_reason[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cancel_reason_code
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        cancel_reason_code
      </code>
      
      . Send as <code>
        cancel_reason_code[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        billing_period
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        billing_period
      </code>
      
      . Send as <code>
        billing_period[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        billing_period_unit
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        billing_period_unit
      </code>
      
      . Send as <code>
        billing_period_unit[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        remaining_billing_cycles
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        remaining_billing_cycles
      </code>
      
      . Send as <code>
        remaining_billing_cycles[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        auto_collection
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        auto_collection
      </code>
      
      . Send as <code>
        auto_collection[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        create_pending_invoices
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        create_pending_invoices
      </code>
      
      . Send as <code>
        create_pending_invoices[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        net_term_days
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        net_term_days
      </code>
      
      . Send as <code>
        net_term_days[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        po_number
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        po_number
      </code>
      
      . Send as <code>
        po_number[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        invoice_notes
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        invoice_notes
      </code>
      
      . Send as <code>
        invoice_notes[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        default_payment_method
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        default_payment_method
      </code>
      
      . Send as <code>
        default_payment_method[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        coupon
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        coupon
      </code>
      
      . Send as <code>
        coupon[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        has_scheduled_changes
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        has_scheduled_changes
      </code>
      
      . Send as <code>
        has_scheduled_changes[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        plan_quantity
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        plan_quantity
      </code>
      
      . Send as <code>
        plan_quantity[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mrr
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        mrr
      </code>
      
      . Send as <code>
        mrr[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        created_at
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        created_at
      </code>
      
      . Send as <code>
        created_at[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        updated_at
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        updated_at
      </code>
      
      . Send as <code>
        updated_at[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        customer
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        customer
      </code>
      
      . Send as <code>
        customer[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        customer_name
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Compares the customer's RESOLVED display name — <code>
        first_name last_name
      </code>
      
      , else <code>
        company
      </code>
      
      , else the legacy <code>
        name
      </code>
      
       — the same string <code>
        customer_name
      </code>
      
       is reported as, so <code>
        contains=priya raghunathan
      </code>
      
       matches a customer who has only the two structured columns. Not a column: <code>
        is_present=false
      </code>
      
       means no name of any kind (filter <code>
        customer_email
      </code>
      
       for the address a nameless row displays instead).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        customer_email
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        customer_email
      </code>
      
      . Send as <code>
        customer_email[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        customer_company
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        customer_company
      </code>
      
      . Send as <code>
        customer_company[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        customer_phone
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        customer_phone
      </code>
      
      . Send as <code>
        customer_phone[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        plan
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Virtual: EXISTS over the subscription's plan items, matched on the plan's public id.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        addon
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Virtual: EXISTS over the subscription's add-on items.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment_method_id
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The <code>
        payment_method_*
      </code>
      
       group asks whether the subscription's CUSTOMER holds ANY stored instrument matching — not which instrument this subscription is pinned to, which is <code>
        default_payment_method
      </code>
      
      . Because the match is an existence test over the customer's methods, a negation (<code>
        is_not
      </code>
      
      , <code>
        not_in
      </code>
      
      ) also returns a customer holding no method at all.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment_method_type
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        payment_method_type
      </code>
      
      . Send as <code>
        payment_method_type[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment_method_status
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        payment_method_status
      </code>
      
      . Send as <code>
        payment_method_status[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment_method_gateway
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        payment_method_gateway
      </code>
      
      . Send as <code>
        payment_method_gateway[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment_method_brand
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The card network — Visa, Mastercard, RuPay — not card-versus-bank, which is <code>
        payment_method_type
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment_method_last4
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        payment_method_last4
      </code>
      
      . Send as <code>
        payment_method_last4[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment_method_exp_month
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        payment_method_exp_month
      </code>
      
      . Send as <code>
        payment_method_exp_month[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment_method_exp_year
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        payment_method_exp_year
      </code>
      
      . Send as <code>
        payment_method_exp_year[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment_method_issuer_country
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        payment_method_issuer_country
      </code>
      
      . Send as <code>
        payment_method_issuer_country[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment_method_sub_type
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The bank-account type, for instruments that have one.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment_method_role
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        payment_method_role
      </code>
      
      . Send as <code>
        payment_method_role[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment_method_gateway_account
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Matched on the gateway account's public id, via the instrument that is registered with it.
    </td>
  </tr>
</tbody>
</table>

## Response

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The object type; always <code>
        list
      </code>
      
      . One of <code>
        list
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      The rows on this page.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.object
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The object type.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.id
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The subscription's id (sub_…).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.status
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The subscription's status. One of <code>
        future
      </code>
      
      , <code>
        in_trial
      </code>
      
      , <code>
        active
      </code>
      
      , <code>
        non_renewing
      </code>
      
      , <code>
        paused
      </code>
      
      , <code>
        cancelled
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.currency
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The subscription's currency (ISO-4217 code).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.current_period_end
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      The current billing term end. NULL while <code>
        in_trial
      </code>
      
       — a trial is not a term, so a trialling subscription reports <code>
        trial_end
      </code>
      
       instead and this is null (one or the other is reported, never both). Use <code>
        next_billing_at
      </code>
      
       for "when is this customer charged again?", which answers across every status.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.next_billing_at
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      When the next invoice will be raised: trial end while in_trial, the scheduled start while future, the first renewal not skipped while active (or the next monthly usage invoice, when it is earlier); null once non_renewing/paused/cancelled, where no further invoice is due
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.bill_usage_monthly
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Metered usage is invoiced every month inside the billing period.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.current_sub_period_start
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      Monthly usage billing: usage before this instant is billed. Null when monthly usage billing is off.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.current_sub_period_end
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      Monthly usage billing: when the next monthly usage invoice is raised. Null when off.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.commitment
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Minimum commitment for one full billing period, or null. See GET /subscriptions/{id}/commitment for the counted fees.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.skipped_renewals
      </code>
    </td>
    
    <td>
      <code>
        array of string · ISO-8601
      </code>
    </td>
    
    <td>
      Upcoming renewals scheduled to be skipped, as the instants the clock renews at. See <code>
        skip_renewal
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.recurring_amount_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      What one billing period charges for the recurring items, in minor units, net of discounts that last more than one period and before tax; null when cancelled or when an item recurs on a different cadence than the subscription
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.revenue_to_date_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      DERIVED, read-only: cash collected on this subscription's invoices, in its currency — succeeded payments minus succeeded refunds. Credits applied to invoices are excluded. Emitted by GET (detail) only.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.revenue_paid_invoices_count
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      How many of this subscription's invoices received a succeeded payment.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.revenue_since
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      The first succeeded payment on this subscription; null when nothing was collected.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.custom_fields
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Stored custom-field values; also flattened onto the object as cf_<name>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.shipping_address_id
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The shipping address this subscription is set to ship to; null when it ships to the customer's default. Emitted by GET (detail), create, and an update that sends it.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.shipping_address
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Where this subscription ships now: its own address, else the customer's default, else null. Invoices record a copy when they are issued.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        has_more
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Whether more rows exist after this page.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        next_cursor
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Opaque; pass as starting_after
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        next_offset
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Present only while has_more; the same opaque token as next_cursor — pass as offset
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        total
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Filtered-set count; first page only
    </td>
  </tr>
</tbody>
</table>

## Status codes

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        200
      </code>
    </td>
    
    <td>
      Success
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        400
      </code>
    </td>
    
    <td>
      Bad limit / unknown filter field, operator or sort key
    </td>
  </tr>
</tbody>
</table>
</template>

<template v-slot:request="">

```bash [Request]
curl "$TMBILLING_URL/v1/businesses/biz_XXXXXXXXXXXX01/subscriptions?limit=10" \
  -H "Authorization: Bearer $TMBILLING_API_KEY"
```

</template>

<template v-slot:response="">
<code-group>

```json [200 OK]
{
  "object": "list",
  "data": [
    {
      "object": "subscription",
      "id": "sub_XXXXXXXXXXXX01",
      "status": "active",
      "currency": "USD",
      "current_period_end": "2026-04-14T09:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "next_offset": "eyJvZmZzZXQiOjEwfQ",
  "total": 2900
}
```

```json [400 Bad Request]
{
  "error": {
    "type": "invalid_request_error",
    "message": "Bad limit / unknown filter field, operator or sort key"
  }
}
```

</code-group>
</template>
</api-operation>


## Sitemap

See the full [sitemap](https://twominutebilling.com/sitemap.md) for all pages.