Coupons, Add-ons and Credit Notes
Coupons
A coupon is a discount you can apply to customers: a percentage or a fixed amount, for some or all plans.
curl -X POST https://api.pimabill.com/api/coupons \
-H "Authorization: Bearer sk_live_a1b2c3d4..." \
-H "Content-Type: application/json" \
-d '{
"code": "WELCOME20",
"name": "20% welcome discount",
"discountType": "PERCENTAGE",
"discountValue": 20,
"maxRedemptions": 100,
"expiresAt": "2026-12-31T23:59:59Z"
}'
For FIXED_AMOUNT, discountValue is an amount and currency is required. appliesToPlanIds limits the coupon to some plans (empty means all).
Apply it to a customer, optionally for one subscription and a number of billing cycles:
curl -X POST https://api.pimabill.com/api/coupons/apply \
-H "Authorization: Bearer sk_live_a1b2c3d4..." \
-H "Content-Type: application/json" \
-d '{ "couponId": "cpn_123", "customerId": "cust_abc123", "usesRemaining": 3 }'
Leave out usesRemaining to apply it forever. DELETE /api/coupons/applied/{id} removes it.
Add-ons
An add-on is a one-time charge you can add to a customer's next invoice, such as a setup fee or premium support, with a price per currency.
curl -X POST https://api.pimabill.com/api/add-ons \
-H "Authorization: Bearer sk_live_a1b2c3d4..." \
-H "Content-Type: application/json" \
-d '{
"name": "Premium support",
"code": "premium_support",
"prices": [{ "currency": "UGX", "amount": 50000 }, { "currency": "USD", "amount": 15 }]
}'
Charge it to a customer; it is included in their next invoice:
curl -X POST https://api.pimabill.com/api/add-ons/apply \
-H "Authorization: Bearer sk_live_a1b2c3d4..." \
-H "Content-Type: application/json" \
-d '{ "addOnId": "ao_123", "customerId": "cust_abc123", "amount": 50000, "currency": "UGX" }'
GET /api/add-ons?code=premium_support finds an add-on by its code. GET /api/add-ons/applied/list shows pending one-time charges, and DELETE /api/add-ons/applied/{id} removes one that has not been invoiced yet.
To sell an add-on on its own, such as a course or a bundle paid once, put it on an invoice by addOnCode. See One-time products & partial payments.
Credit notes
A credit note records money owed back to a customer against an invoice: a duplicate charge, an unhappy customer, or a changed order.
curl -X POST https://api.pimabill.com/api/credit-notes \
-H "Authorization: Bearer sk_live_a1b2c3d4..." \
-H "Content-Type: application/json" \
-d '{
"invoiceId": "inv_123",
"customerId": "cust_abc123",
"amount": 25000,
"currency": "UGX",
"reason": "PRODUCT_UNSATISFACTORY"
}'
reason is one of DUPLICATE, PRODUCT_UNSATISFACTORY, ORDER_CHANGE or OTHER.
A credit note starts as DRAFT and can be edited. POST /api/credit-notes/{id}/finalize makes it final and sends a credit_note.finalized webhook; POST /api/credit-notes/{id}/void cancels it. Finalizing records the credit; to return money, refund the payment or top up the customer's wallet.