Recipes

Upgrades and downgrades

Change a subscription's items, learn how the difference is prorated, and decide whether to apply the change now or schedule it for the end of the term.

To upgrade or downgrade a subscription, you change its items. tmbilling prorates the difference, and you decide whether the change applies now or at the end of the term.

Select change or update_for_items

Two endpoints change a subscription's items. They behave differently.

EndpointYou sendtmbilling does
POST /subscriptions/{sub}/changea deltaApplies your additions, removals and quantity changes. Leaves every item you don't mention untouched.
POST /subscriptions/{sub}/update_for_itemsthe complete item listMakes the subscription match your list exactly. Removes anything you left out.
Send one item to update_for_items on a subscription with a plan and three add-ons, and you keep that one item and credit the other four. If you mean "change this one thing", use change.

Upgrade a subscription

Swap one price for another in a single call:

curl -X POST $TMBILLING_URL/v1/businesses/$BIZ/subscriptions/$SUB/change \
  -H "Authorization: Bearer $TMBILLING_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "price": "pro-monthly-usd", "quantity": 1 },
      { "price": "starter-monthly-usd", "remove": true }
    ]
  }'

Understand the proration

tmbilling prorates both sides of the change and writes each as a real invoice line with its own ledger entries:

Credit the unused portion

You get a credit for the removed item's remaining time in the current period, pro rata.

Charge the new item

tmbilling charges the new item pro rata, from now to the end of the current period.

Net it into an invoice

An upgrade usually nets to a charge. A downgrade usually nets to a credit.

The renewal date does not move. Your customer stays on their existing term.

A downgrade that nets to a credit adds that credit to the customer's balance, and tmbilling applies it to their next invoice. To refund the money instead, issue a refundable credit note — the two have different tax and accounting consequences. See Credits and the ledger.

Estimate before you charge

POST/v1/businesses/{biz}/subscriptions/{sub}/estimate

Send the same body you would send to change. You get back the exact proration, tax and credit application, and tmbilling changes nothing.

Show that number to your customer first. It is what lets you say "you pay $18.34 today, then $49.00 monthly from 14 October" and be right.

Change a quantity

Adding or removing seats uses the same endpoint:

curl -X POST $TMBILLING_URL/v1/businesses/$BIZ/subscriptions/$SUB/change \
  -H "Authorization: Bearer $TMBILLING_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{ "items": [{ "price": "seats-monthly-usd", "quantity": 25 }] }'

Increase the quantity and tmbilling prorates a charge for the new seats. Decrease it and you get a prorated credit for the ones you removed.

Schedule a downgrade for the end of the term

Apply upgrades immediately — your customer wants what they just paid for. Schedule downgrades for the end of the term instead. Your customer has already paid for this period, so removing their access now while keeping the money creates a support ticket.

POST/v1/businesses/{biz}/subscriptions/{sub}/schedule
curl -X POST $TMBILLING_URL/v1/businesses/$BIZ/subscriptions/$SUB/schedule \
  -H "Authorization: Bearer $TMBILLING_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{
    "type": "change",
    "effective_at": "2026-10-14T00:00:00Z",
    "items": [{ "price": "starter-monthly-usd", "quantity": 1 }]
  }'

A scheduled change is a real object. List it, show your customer "your plan changes on 14 October", and withdraw it if they change their mind:

GET/v1/businesses/{biz}/subscriptions/{sub}/scheduled_changes
DELETE/v1/businesses/{biz}/scheduled_changes/{sch}

Add or remove a single item

To change one add-on, use the narrower endpoints instead of sending a whole delta:

POST/v1/businesses/{biz}/subscriptions/{sub}/items
DELETE/v1/businesses/{biz}/subscriptions/{sub}/items/{item}

Both prorate the same way as change.

Reprice a plan

Editing a price affects new subscriptions only. Existing subscribers keep the price they signed up on, so a price edit cannot silently reprice your customer base.

To move existing customers, create the new price and change their subscriptions onto it. Plan that as a migration with a notice period, not as a PATCH.

Related

Usage-based billing

Charge for what customers use: create a usage price, record usage with idempotency keys, show the running total, and bill it in arrears with the plan fee.

Coupons

Create reusable coupons, generate single-use code sets for a campaign, apply a one-off discount without a catalog object, and see where each shows on invoices.

Copyright © 2026