---
title: "Coupons and discounts"
description: "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."
canonical_url: "https://twominutebilling.com/help/developers/recipes/coupons"
---
# Coupons and discounts

> 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.

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.

```bash
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:

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

Or apply and remove it later:

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



</endpoint>

<endpoint method="DELETE" path="/v1/businesses/{biz}/subscriptions/{sub}/discount">



</endpoint>

## Generate single-use codes for a campaign

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

<endpoint method="POST" path="/v1/businesses/{biz}/coupon_sets">



</endpoint>

<endpoint method="POST" path="/v1/businesses/{biz}/coupon_sets/{set}/codes">



</endpoint>

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.

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



</endpoint>

```bash
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`.

<note title="One discount per subscription">

A subscription holds one discount. tmbilling refuses a second. A discount you pass at signup
applies to the first invoice, not to the next renewal.

</note>

## Apply a discount before tax

tmbilling applies discounts before it calculates tax:

```text
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](https://twominutebilling.com/help/developers/concepts/credits).

## 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:

```bash
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](https://twominutebilling.com/product/subscriptions)
- [How discounts apply on an invoice](https://twominutebilling.com/help/developers/concepts/invoices)


## Sitemap

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