---
title: "Estimate a change, add and/or removal"
description: "Proration + tax, dry-run."
canonical_url: "https://twominutebilling.com/help/developers/api-reference/subscriptions/estimate-a-change"
---
# Estimate a change, add and/or removal

> Proration + tax, dry-run.

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

No writes. Prices modified lines, added items and removals in ONE preview, so a confirmation screen can state the whole amount that will move. A change can raise TWO documents — a proration invoice and a credit note — so `total_minor` is the DIFFERENCE between them (negative when the customer is credited) and is NOT `subtotal_minor + tax_minor`: `tax_minor`/`tax_lines` describe the invoice only, and the note’s own tax is in `credit_note_total_minor`. The note is spent in order: first relieving whatever the term's own invoices are still OWED (`credit_applied_to_open_invoices_minor` — the customer's debt is cancelled rather than refunded), then against this invoice, and only what is left over is `refundable_credit_added_minor`, which goes back on the balance. On a fully-paid term the first slice is absent and the note simply exceeds the invoice. `next_renewal` prices the NEXT renewal invoice as it will look after this change (tax and coupons in, that credit applied) so a confirmation screen never has to sum line amounts itself. On an in-trial subscription nothing is charged now: `amount_due_minor` is 0, `due_at_trial_end` is set, `next_renewal` is null, and the lines describe the full post-change composition the trial-end invoice will raise.

## 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>
  
  <tr>
    <td>
      <code>
        sub
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      Subscription id (sub_…)
    </td>
  </tr>
</tbody>
</table>

## Body

The request body is **required**.

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

<tbody>
  <tr>
    <td>
      <code>
        coupon_code
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      A coupon to apply AS PART OF this change. Applied inside the change's own transaction, BEFORE its proration invoice is raised — so the proration is discounted, which is the intended behaviour. Posting it as a separate call afterwards bills the proration at list price. <code>
        POST …/estimate
      </code>
      
       takes the same field and previews the same result.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        coupon_ids
      </code>
    </td>
    
    <td>
      <code>
        array of string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The same coupon as <code>
        coupon_code
      </code>
      
      , as a list. A subscription carries ONE discount at a time, so more than one entry is refused (400), as is a <code>
        coupon_code
      </code>
      
       naming a different coupon.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        manual_discount
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      A manual discount to apply as part of this change — same shape <code>
        POST …/subscriptions/{sub}/manual_discount
      </code>
      
       takes, minus <code>
        note
      </code>
      
      , so one screen sends one body shape to the preview and the booking. <code>
        duration
      </code>
      
       defaults to <code>
        forever
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        manual_discount.type
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      The discount type. One of <code>
        percent
      </code>
      
      , <code>
        amount
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        manual_discount.value
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      1–100 for <code>
        percent
      </code>
      
      ; minor units for <code>
        amount
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        manual_discount.duration
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      How long the discount lasts. One of <code>
        one_time
      </code>
      
      , <code>
        forever
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        remove_discount
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Remove the subscription's active discount (coupon or manual) as part of this change, inside its transaction and BEFORE the proration invoice is raised — so that invoice bills without it. With <code>
        coupon_code
      </code>
      
       or <code>
        manual_discount
      </code>
      
       it swaps the discount in one edit. On the estimate it prices the same order.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        changes
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Existing items to change.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        changes.item
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      The subscription item's id (si_…).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        changes.price
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The new price's id (a slug id, e.g. <code>
        pro-monthly-usd
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        changes.quantity
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The new quantity.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        changes.unit_price_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Custom price override (flat/per-unit only), minor units
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        adds
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Items that would be added (<code>
        POST …/items
      </code>
      
      ). A plan-scoped differential price is resolved exactly as the add would resolve it.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        adds.price
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      The price's id (a slug id, e.g. <code>
        pro-monthly-usd
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        adds.quantity
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The quantity.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        adds.unit_price_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      A unit price for this add, in minor units, in place of the price's own.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        removes
      </code>
    </td>
    
    <td>
      <code>
        array of string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Subscription item ids that would be removed (<code>
        DELETE …/items/:id
      </code>
      
      ); each previews a prorated credit for unused time.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        at
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The time to estimate for (ISO-8601 UTC).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reset_term
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      True to estimate with a new term starting at <code>
        at
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        prorate
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Mirrors SubscriptionChange's <code>
        prorate
      </code>
      
      , so a preview of an unprorated change quotes what that change will actually book. False suppresses the prorated credit and charge; on a term reset the full new-term charge survives and only the unused-time credit drops, so clearing it there RAISES the total rather than zeroing it. Defaults to <code>
        true
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        coupons
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      As on <code>
        POST …/change
      </code>
      
      : the preview drops the same coupons. Not with a scheduled <code>
        change_option
      </code>
      
       (400). One of <code>
        keep
      </code>
      
      , <code>
        drop
      </code>
      
      , <code>
        keep_if_valid
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        downgrade_credit
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      As on <code>
        POST …/change
      </code>
      
      : decides <code>
        refunded_to_payment_method_minor
      </code>
      
       and <code>
        change_policy.credit_handling
      </code>
      
      . Not with a scheduled <code>
        change_option
      </code>
      
       (400). One of <code>
        credit_balance
      </code>
      
      , <code>
        refund
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        change_option
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      <code>
        specific_date
      </code>
      
       previews the edit as <code>
        POST …/schedule
      </code>
      
       (type <code>
        change
      </code>
      
      ) applies it at <code>
        changes_scheduled_at
      </code>
      
      , priced from today's state. A scheduled change carries only <code>
        changes
      </code>
      
      /<code>
        adds
      </code>
      
      /<code>
        removes
      </code>
      
      , so a coupon, manual discount, <code>
        prorate
      </code>
      
       or <code>
        reset_term
      </code>
      
       alongside it is refused (400). <code>
        end_of_term
      </code>
      
       previews it as a change scheduled for the current term end (the trial end in a trial) books it at that instant: nothing is left to prorate, and <code>
        next_renewal
      </code>
      
       is the renewal at the new composition. <code>
        prorate
      </code>
      
       and <code>
        reset_term
      </code>
      
       are refused (400); a coupon or manual discount is previewed onto that renewal. One of <code>
        immediately
      </code>
      
      , <code>
        specific_date
      </code>
      
      , <code>
        end_of_term
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        changes_scheduled_at
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Required with <code>
        change_option=specific_date
      </code>
      
      ; must be in the future and inside the current term.
    </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>
        estimate
      </code>
      
      . One of <code>
        estimate
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        currency
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The currency code.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        lines
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      The quoted lines.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        subtotal_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      The sum of the lines, in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        discount_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Every discount off the subtotal, in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tax_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      The tax, in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tax_lines
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      The tax, split into the rows the invoice prints.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        discount_lines
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      The discount, split into named rows.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        total_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Subtotal minus discount plus tax, in minor units. Goes negative on a downgrade.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        immediate_charge
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      True if the customer is charged now; false if the net is a credit.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        credits_applied_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Refundable and excess credit that the estimate applies, in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        promotional_credits_applied_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Promotional credit that the estimate applies, in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        promotional_discount_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Promotional credit as a pre-tax discount, in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        refundable_credits_applied_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Refundable credit that the estimate applies, in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        excess_payments_applied_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Excess payments that the estimate applies, in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        grant_credits_pre_tax_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Credit grants applied before tax (promotional, and paid credit taxed at purchase). Already off <code>
        total_minor
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        grant_credits_post_tax_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Money credit grants taxed at use, applied after tax. Included in <code>
        credits_applied_minor
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        credit_note_total_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      The total of the credit notes the change raises, tax included, in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        refunded_to_payment_method_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Change estimate only, with <code>
        billing_rules_config.downgrade_credit: refund
      </code>
      
       (or the portal customer's selection): the part of the change's credit that is refunded to the card or bank payments that paid. The rest stays as <code>
        refundable_credit_added_minor
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        refundable_credit_added_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Credit that lands on the customer's balance, in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        credit_applied_to_open_invoices_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Credit that pays down open invoices, in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        credit_applied_to_this_invoice_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Credit that offsets this invoice, in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        credit_destinations
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      Where the credit goes.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        credited_period_start
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      Start of the period that is credited (ISO 8601).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        credited_period_end
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      End of the period that is credited (ISO 8601).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        invoice_total_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      The total of the invoice this change raises, in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        invoice_subtotal_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      The subtotal of the invoice this change raises, in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        credit_returned_to_buckets_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Credit that returns to promotional or excess balance, in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        credit_returned_to_grants_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Credit given back to the credit grants the source invoices drew, in minor units. Inside credit_returned_to_buckets_minor.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        credit_stranded_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Credit that reaches nobody, in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        credit_routing_over_claimed_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Credit that routing claimed in excess, in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        amount_due_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      What the customer is asked to pay now, in minor units.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        next_renewal
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      The renewal invoice that the change leads to.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        term_reset
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      True if the change starts a new billing term.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        new_period_end
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      The end of the new term (ISO 8601), or null.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        due_at_trial_end
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      When the first charge is due, if the subscription starts in a trial.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        in_term_reactivation
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Set when a reactivation can resume the current term.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        in_term_available
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      True if the subscription can resume its current term.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        scheduled_change
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Renewal estimate only: the scheduled change that runs before this renewal and whose items it prices.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mandate_shortfall
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Set when the amount is above the mandate's per-debit limit.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        debits_in_flight
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      Debits that are already under way.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        priced_at
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      Only on <code>
        POST …/subscriptions/{sub}/estimate
      </code>
      
      : the instant these amounts are priced at. Send it to <code>
        /change
      </code>
      
       with <code>
        quote
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        quote
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Only on <code>
        POST …/subscriptions/{sub}/estimate
      </code>
      
      : a hash of the amounts shown. Send it to <code>
        /change
      </code>
      
       with <code>
        priced_at
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        change_policy
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Only on <code>
        POST …/subscriptions/{sub}/estimate
      </code>
      
      : the business's plan-change rules for this edit.
    </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>
      Estimate
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        400
      </code>
    </td>
    
    <td>
      Invalid change, or a coupon the apply would refuse: not yet valid, expired, at its redemption limit, or used by this customer as often as it allows
    </td>
  </tr>
</tbody>
</table>
</template>

<template v-slot:request="">

```bash [Request]
curl -X POST "$TMBILLING_URL/v1/businesses/biz_XXXXXXXXXXXX01/subscriptions/sub_XXXXXXXXXXXX01/estimate" \
  -H "Authorization: Bearer $TMBILLING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "coupon_code": "welcome-10",
    "remove_discount": false
  }'
```

</template>

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

```json [200 OK]
{
  "object": "estimate",
  "currency": "USD",
  "lines": [
    {
      "description": "Pro plan (monthly)",
      "amount_minor": 4900
    }
  ],
  "subtotal_minor": 4900,
  "discount_minor": 490,
  "tax_minor": 882,
  "tax_lines": [
    {
      "label": "VAT (20.00%)",
      "amount_minor": 980
    }
  ],
  "discount_lines": [
    {
      "label": "welcome-10",
      "amount_minor": 490
    }
  ],
  "total_minor": 5292,
  "immediate_charge": false,
  "credits_applied_minor": 0,
  "promotional_credits_applied_minor": 0,
  "promotional_discount_minor": 0,
  "refundable_credits_applied_minor": 0,
  "excess_payments_applied_minor": 0,
  "grant_credits_pre_tax_minor": 0,
  "grant_credits_post_tax_minor": 0,
  "credit_note_total_minor": 2900,
  "refunded_to_payment_method_minor": 0,
  "refundable_credit_added_minor": 2900,
  "credit_applied_to_open_invoices_minor": 2900,
  "credit_applied_to_this_invoice_minor": 2900,
  "credit_destinations": [
    {
      "kind": "refundable",
      "destination": "balance",
      "amount_minor": 1200,
      "invoice": "inv_XXXXXXXXXXXX01"
    }
  ],
  "credited_period_start": "2026-03-14T09:30:00Z",
  "credited_period_end": "2026-04-14T09:30:00Z",
  "invoice_total_minor": 2900,
  "invoice_subtotal_minor": 2900,
  "credit_returned_to_buckets_minor": 2900,
  "credit_returned_to_grants_minor": 2900,
  "credit_stranded_minor": 2900,
  "credit_routing_over_claimed_minor": 2900,
  "amount_due_minor": 5292,
  "next_renewal": {
    "date": "2026-03-14T09:30:00Z",
    "lines": [
      {
        "description": "Everything a growing team needs.",
        "amount_minor": 2900
      }
    ],
    "subtotal_minor": 2900,
    "discount_minor": 0,
    "tax_minor": 0,
    "tax_lines": [
      {
        "label": "VAT (20.00%)",
        "amount_minor": 980
      }
    ],
    "total_minor": 2900,
    "credits_applied_minor": 0,
    "amount_due_minor": 0
  },
  "term_reset": false,
  "new_period_end": "2026-04-14T09:30:00Z",
  "due_at_trial_end": "2026-04-14T09:30:00Z",
  "in_term_reactivation": {
    "current_period_end": "2026-04-14T09:30:00Z",
    "invoice": {
      "id": "inv_XXXXXXXXXXXX01",
      "number": "INV-1001",
      "status": "payment_due",
      "outstanding_minor": 2900
    },
    "collects_now": false
  },
  "in_term_available": false,
  "scheduled_change": {
    "id": "3f6c1b9e-8a2d-4c5e-9f10-2b7d4e6a8c01",
    "type": "change",
    "effective_at": "2026-03-14T09:30:00Z"
  },
  "mandate_shortfall": {
    "payment_method": "pm_XXXXXXXXXXXX01",
    "ceiling_minor": 2900,
    "amount_minor": 2900,
    "currency": "INR",
    "rail": "upi",
    "reauthorized_ceiling_minor": 2900,
    "needs_authentication_even_if_raised": false
  },
  "debits_in_flight": [
    {
      "invoice": "inv_XXXXXXXXXXXX01",
      "awaiting_buyer": false,
      "kind": "payment"
    }
  ],
  "priced_at": "2026-03-14T09:30:00Z",
  "quote": "9f2c4e1a7b3d5c6e8f0a1b2c3d4e5f60",
  "change_policy": {
    "direction": "upgrade",
    "timings": [
      "now"
    ],
    "default_timing": "now",
    "blocked": {
      "code": "invoices_unpaid",
      "message": "Requested by the customer."
    },
    "prorate": false,
    "reset_term": false,
    "invoice_immediately": false,
    "credit_handling": "credit_balance",
    "coupons": "keep",
    "on_charge_failure": "start_dunning",
    "plan_credits": "full",
    "allowances": "new_window"
  }
}
```

```json [400 Bad Request]
{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid change, or a coupon the apply would refuse: not yet valid, expired, at its redemption limit, or used by this customer as often as it allows"
  }
}
```

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


## Sitemap

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