Coupons and discounts

tmbilling gives you three ways to discount a subscription. Select the one that matches how you intend to reuse it.

Create a reusable coupon

A coupon is a catalog object: a percent or a fixed amount, with validity dates and constraints on which products it applies to. Use one when many customers get the same offer.

curl -X POST $TMBILLING_URL/v1/businesses/$BIZ/coupons \
  -H "Authorization: Bearer $TMBILLING_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{ "id": "WELCOME20", "name": "20% off the first 3 months" }'

Apply it when you create the subscription:

-d '{ "items": [{ "price": "pro-monthly-usd" }], "coupon_ids": ["WELCOME20"] }'

Or apply and remove it later:

Generate single-use codes for a campaign

A coupon set gives every recipient their own code, so you can tell who redeemed what.

Ask for a number of codes, or supply your own list. You can archive an individual code while it is still unredeemed, and clear the unused remainder of a finished campaign in one call.

Apply a one-off discount

Use a manual discount when there is no catalog object behind the offer — a negotiated concession, or a goodwill gesture on a single account.

curl -X POST $TMBILLING_URL/v1/businesses/$BIZ/subscriptions/$SUB/manual_discount \
  -H "Authorization: Bearer $TMBILLING_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{ "type": "percent", "value": 15, "duration": "forever", "note": "Renewal negotiation" }'

Set type to percent for a whole percent from 1 to 100, or amount for integer minor units. Set duration to one_time or forever.

Apply a discount before tax

tmbilling applies discounts before it calculates tax:

lines → discounts → promotional credits → TAX → refundable credits → excess payments → charge

A 20% coupon reduces the taxable amount, so the tax drops with it. Credits work differently: they apply after tax, so they never reduce it. See Credits and the ledger.

Let customers enter their own codes

Set allow_customer_coupons on the business to control whether a buyer can type a code at hosted checkout. Leave it off and you apply every code yourself, through the API or the dashboard.

Preview the result

Estimate the subscription with the coupon attached:

curl -X POST $TMBILLING_URL/v1/businesses/$BIZ/customers/$CUS/subscription_estimate \
  -H "Authorization: Bearer $TMBILLING_API_KEY" -H "Content-Type: application/json" \
  -d '{ "items": [{ "price": "pro-monthly-usd" }], "coupon_ids": ["WELCOME20"] }'

You get the discount line, the reduced tax and the final total. Display those numbers on your checkout page rather than calculating them in your front end.

Void an invoice without spending the code

When you void an invoice, tmbilling returns the coupon redemptions it consumed, so a single-use code survives a cancelled document.

Archiving a coupon with DELETE is a soft delete. It stops new applications and leaves existing discounted subscriptions alone.

Related

• Discounts and credit on subscriptions
• How discounts apply on an invoice