---
title: "Subscriptions"
description: "Follow a subscription through its statuses and terms, select one of the two endpoints that change items, and estimate every money-moving call before you run it."
canonical_url: "https://twominutebilling.com/help/developers/concepts/subscriptions"
---
# Subscriptions

> Follow a subscription through its statuses and terms, select one of the two endpoints that change items, and estimate every money-moving call before you run it.

A subscription holds many items: one line per price, each with a quantity. A plan, three add-ons
and a metered line share one renewal date and one invoice.

Once you create it, the billing clock owns it. Renewal, invoice generation, collection and dunning
happen without further calls from you.

## Statuses

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      What it means
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        future
      </code>
    </td>
    
    <td>
      You gave it a start date that has not arrived.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        in_trial
      </code>
    </td>
    
    <td>
      It is in its trial period. tmbilling charges nothing yet.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        active
      </code>
    </td>
    
    <td>
      It is billing normally.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        non_renewing
      </code>
    </td>
    
    <td>
      It runs to the end of the current term, then stops. You get this from "cancel at period end", and a subscription that runs out of billing cycles reaches it on its own.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        paused
      </code>
    </td>
    
    <td>
      tmbilling does not bill it while paused.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cancelled
      </code>
    </td>
    
    <td>
      Terminal.
    </td>
  </tr>
</tbody>
</table>

<note title="There is no past_due status">

A failed payment belongs to the invoice, not the subscription. The invoice moves to `payment_due`
and dunning starts, while the subscription can stay `active` throughout.

You configure what happens when the retries run out — it may cancel, and it may not. The
subscription carries counters for what is owed rather than a status that conflates money with
access. See [Failed payments and dunning](https://twominutebilling.com/help/developers/recipes/failed-payments).

</note>

## Terms

A subscription has a current term: the period you bill it for. At the end of each term tmbilling
rolls it forward and raises the invoice for the period just begun.

Recurring lines bill in advance. Usage bills in arrears, for the period that just closed.

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      What it does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        trial_days
      </code>
    </td>
    
    <td>
      integer
    </td>
    
    <td>
      Starts the subscription <code>
        in_trial
      </code>
      
      . tmbilling makes the first charge when the trial ends.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        start_date
      </code>
    </td>
    
    <td>
      ISO-8601
    </td>
    
    <td>
      Backdates or future-dates the period start. A future date gives you a <code>
        future
      </code>
      
       subscription.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        billing_anchor
      </code>
    </td>
    
    <td>
      ISO-8601
    </td>
    
    <td>
      Fixes the first period end, so you can align a subscription to a calendar billing date instead of its signup date.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        remaining_billing_cycles
      </code>
    </td>
    
    <td>
      integer
    </td>
    
    <td>
      Sets a fixed number of renewals. At zero the subscription becomes <code>
        non_renewing
      </code>
      
       rather than cancelled, which matters to your customer's access.
    </td>
  </tr>
</tbody>
</table>

<endpoint method="POST" path="/v1/businesses/{biz}/subscriptions/{sub}/change_term_end">



</endpoint>

Moves the current term's end boundary, when you need the next invoice on a specific day.

## Change the items

Two endpoints change items, and picking the wrong one is the usual mistake:

<table>
<thead>
  <tr>
    <th>
      Endpoint
    </th>
    
    <th>
      You send
    </th>
    
    <th>
      tmbilling does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        POST /subscriptions/{sub}/change
      </code>
    </td>
    
    <td>
      a delta
    </td>
    
    <td>
      Applies your additions, removals and quantity changes, and leaves everything you don't mention alone.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /subscriptions/{sub}/update_for_items
      </code>
    </td>
    
    <td>
      the complete item list
    </td>
    
    <td>
      Makes the subscription match your list, removing anything absent from it.
    </td>
  </tr>
</tbody>
</table>

Both prorate immediately. tmbilling credits the unused portion of what you removed, charges the
new item pro rata, and writes both as invoice lines and ledger entries.

See [Upgrades and downgrades](https://twominutebilling.com/help/developers/recipes/plan-changes).

## Estimate before you charge

Every money-moving call has a dry run that returns the real numbers and moves nothing:

<table>
<thead>
  <tr>
    <th>
      Estimate
    </th>
    
    <th>
      Tells you
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        POST /customers/{cus}/subscription_estimate
      </code>
    </td>
    
    <td>
      What the first invoice will be
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /subscriptions/{sub}/estimate
      </code>
    </td>
    
    <td>
      What a change, addition or removal will cost
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /subscriptions/{sub}/cancel_estimate
      </code>
    </td>
    
    <td>
      What cancelling does to the money
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /subscriptions/{sub}/reactivate_estimate
      </code>
    </td>
    
    <td>
      What reactivating will invoice
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET /subscriptions/{sub}/renewal_estimate
      </code>
    </td>
    
    <td>
      The next renewal amount
    </td>
  </tr>
</tbody>
</table>

Show one to your customer before you charge them.

## Schedule a change instead of applying it

Anything dated can wait:

<endpoint method="POST" path="/v1/businesses/{biz}/subscriptions/{sub}/schedule">



</endpoint>

Schedules a future-dated `cancel`, `pause`, `resume` or `change`.

A pending schedule is a real object. List it, show it to your customer, and withdraw it if they
change their mind:

<endpoint method="GET" path="/v1/businesses/{biz}/subscriptions/{sub}/scheduled_changes">



</endpoint>

<endpoint method="DELETE" path="/v1/businesses/{biz}/scheduled_changes/{sch}">



</endpoint>

## Cancel, pause and resume

Each of these takes a full option set rather than a single boolean, because each raises the same
questions: what happens to unbilled charges, to the outstanding balance and to refundable credit,
and what reason to record.

<endpoint method="POST" path="/v1/businesses/{biz}/subscriptions/{sub}/cancel">



</endpoint>

<endpoint method="POST" path="/v1/businesses/{biz}/subscriptions/{sub}/pause">



</endpoint>

<endpoint method="POST" path="/v1/businesses/{biz}/subscriptions/{sub}/resume">



</endpoint>

<endpoint method="POST" path="/v1/businesses/{biz}/subscriptions/{sub}/reactivate">



</endpoint>

A `resume` inside the paid term keeps that term and charges nothing. A resume after it ends starts
a new term at the resume and always bills it: `charges_handling` is `invoice_immediately` or
`add_to_unbilled_charges`, and an omitted value takes the business's
`pause_config.charges_on_resume` (default `invoice_immediately`. `next_renewal` is a deprecated alias of `add_to_unbilled_charges`.). API, portal and scheduled resumes follow the same rule.

`reactivate` both clears a pending cancellation and restarts a subscription that already ended.
Run the estimate to see which one you are about to pay for.

## Add a mid-cycle charge

<endpoint method="POST" path="/v1/businesses/{biz}/subscriptions/{sub}/charges">



</endpoint>

Adds a one-off charge. Invoice it immediately, or fold it into the next renewal.

Deferred charges wait as unbilled charges until tmbilling sweeps them into the next invoice:

<endpoint method="GET" path="/v1/businesses/{biz}/subscriptions/{sub}/unbilled_charges">



</endpoint>

## Related

- [Upgrades, downgrades and proration](https://twominutebilling.com/help/developers/recipes/plan-changes)
- [Free trials](https://twominutebilling.com/help/developers/recipes/trials)
- [Manage subscriptions in the dashboard](https://twominutebilling.com/help/guides/customers-and-subscriptions)


## Sitemap

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