Skip to content

Commit 8ed74b4

Browse files
pierrepierre
committed
Revert "Remove new pages aviate-credits-refunds.adoc aviate-subscription-lifecycle.adoc until we clear context"
This reverts commit 8a3d999.
1 parent c2d952e commit 8ed74b4

3 files changed

Lines changed: 498 additions & 0 deletions

File tree

‎html5/_main_toc.html.slim‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -333,6 +333,12 @@ nav.sidebar-nav
333333
li
334334
a.nav-link href="/latest/aviate-coupons.html"
335335
| Coupons
336+
li
337+
a.nav-link href="/latest/aviate-subscription-lifecycle.html"
338+
| Subscription Lifecycle
339+
li
340+
a.nav-link href="/latest/aviate-credits-refunds.html"
341+
| Credits & Refunds
336342
li
337343
a.nav-link href="/latest/aviate-tax.html"
338344
| Tax

‎userguide/aviate/aviate-credits-refunds.adoc‎

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
= Credits, Refunds & Invoice Adjustments
2+
3+
:card-badge: Premium
4+
:card-title: Aviate
5+
:card-link: https://aviate.killbill.io/
6+
:card-description:
7+
include::{sourcedir}/includes/premium-card.adoc[]
8+
9+
== Overview
10+
11+
Billing corrections are a routine part of operations — handling disputes, issuing goodwill credits, correcting invoice errors, and processing refunds. This guide covers Kill Bill account credits, invoice adjustments, invoice voiding, and payment refunds, with Aviate-specific context on how these operations interact with wallets, tax, and revenue recognition.
12+
13+
NOTE: These operations use *Kill Bill core APIs* (base path `/1.0/kb/`) with *Basic authentication* (`-u admin:password`) and tenant headers. Aviate's wallet credits (`CREDIT_FREE`, `CREDIT_PAID`) are *separate* from Kill Bill's native account credits. For Aviate wallet credits, see https://docs.killbill.io/latest/aviate-wallet.html[Wallet Guide].
14+
15+
== Prerequisites
16+
17+
* A running Kill Bill instance with the https://docs.killbill.io/latest/how-to-install-the-aviate-plugin.html[Aviate plugin installed].
18+
* Kill Bill admin credentials (Basic auth — `admin:password` by default).
19+
* Tenant API key and secret (`X-Killbill-ApiKey` / `X-Killbill-ApiSecret`).
20+
* The target account ID, invoice ID, or payment ID depending on the operation.
21+
22+
== Aviate Wallet Credits vs. Kill Bill Account Credits
23+
24+
Aviate wallet credits and Kill Bill account credits are two distinct mechanisms. Understanding the difference is important to avoid confusion.
25+
26+
[cols="2,3,3", options="header"]
27+
|===
28+
| Feature | Aviate Wallet Credits | Kill Bill Account Credits
29+
30+
| Created via
31+
| `POST /plugins/aviate-plugin/v1/wallet/\{id}/credit` (Bearer token)
32+
| `POST /1.0/kb/credits` (Basic auth)
33+
34+
| Scope
35+
| Wallet-level (tied to a specific wallet)
36+
| Account-level (applied to any invoice)
37+
38+
| Expiration
39+
| Configurable per credit
40+
| No expiration
41+
42+
| Top-off
43+
| Automatic (via `TOP_OFF_FIXED` or `TOP_OFF_TARGET`)
44+
| Manual only
45+
46+
| Invoicing
47+
| Paid credits trigger an invoice; free credits do not
48+
| Generates a credit memo (CBA) invoice
49+
50+
| Usage
51+
| Consumed by usage-based invoicing against the wallet
52+
| Applied as credit-balance-adjustment to the next invoice
53+
54+
| Authentication
55+
| Bearer token (Aviate plugin API)
56+
| Basic auth (Kill Bill core API)
57+
|===
58+
59+
IMPORTANT: Adding a Kill Bill account credit does *not* increase the Aviate wallet balance, and vice versa. They are independent systems.
60+
61+
== Add Account Credit
62+
63+
Account credits create a credit-balance-adjustment (CBA) that is automatically applied to the next invoice. Use this for goodwill credits, billing error corrections, or service outage compensation.
64+
65+
[source,bash]
66+
----
67+
curl -v -X POST \
68+
-u admin:password \
69+
-H "X-Killbill-ApiKey: my-tenant" \
70+
-H "X-Killbill-ApiSecret: my-secret" \
71+
-H "X-Killbill-CreatedBy: admin" \
72+
-H "Content-Type: application/json" \
73+
-d '{
74+
"accountId": "{accountId}",
75+
"creditAmount": 15.00,
76+
"currency": "USD",
77+
"description": "Customer goodwill credit"
78+
}' \
79+
"http://127.0.0.1:8080/1.0/kb/credits"
80+
----
81+
82+
*Expected result:* A credit memo invoice is generated for the specified amount. The credit is automatically applied to offset the next invoice balance on the account.
83+
84+
== Adjust an Invoice Item
85+
86+
Invoice item adjustments reduce the amount of a specific line item on an existing invoice. This is useful for partial credits — for example, compensating a customer for a partial service outage without voiding the entire invoice.
87+
88+
[source,bash]
89+
----
90+
curl -v -X POST \
91+
-u admin:password \
92+
-H "X-Killbill-ApiKey: my-tenant" \
93+
-H "X-Killbill-ApiSecret: my-secret" \
94+
-H "X-Killbill-CreatedBy: admin" \
95+
-H "Content-Type: application/json" \
96+
-d '{
97+
"accountId": "{accountId}",
98+
"invoiceItemId": "{invoiceItemId}",
99+
"amount": 5.00,
100+
"description": "Partial service outage credit"
101+
}' \
102+
"http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}"
103+
----
104+
105+
*Expected result:* An adjustment item is added to the invoice, reducing the balance by the specified amount. The invoice total is updated accordingly. If the invoice was already paid, the adjustment creates an account credit (CBA) for the adjusted amount.
106+
107+
== Void an Invoice
108+
109+
Voiding an invoice reverses all its items and sets the invoice status to `VOID`. This is a full reversal — use it when the entire invoice was generated in error.
110+
111+
[source,bash]
112+
----
113+
curl -v -X PUT \
114+
-u admin:password \
115+
-H "X-Killbill-ApiKey: my-tenant" \
116+
-H "X-Killbill-ApiSecret: my-secret" \
117+
-H "X-Killbill-CreatedBy: admin" \
118+
"http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}/voidInvoice"
119+
----
120+
121+
*Expected result:* All invoice items are reversed. The account balance is adjusted accordingly.
122+
123+
IMPORTANT: You *cannot* void an invoice that has payments associated with it. You must refund the payments first, then void the invoice.
124+
125+
== Refund a Payment
126+
127+
Refunds return money to the customer for a previous payment. Kill Bill supports two refund modes depending on the `isAdjusted` flag.
128+
129+
=== Refund with Invoice Adjustment
130+
131+
When `isAdjusted` is `true`, the refund also adjusts the invoice — the invoice balance is reduced by the refund amount. Use this when you want to both return money and correct the invoice.
132+
133+
[source,bash]
134+
----
135+
curl -v -X POST \
136+
-u admin:password \
137+
-H "X-Killbill-ApiKey: my-tenant" \
138+
-H "X-Killbill-ApiSecret: my-secret" \
139+
-H "X-Killbill-CreatedBy: admin" \
140+
-H "Content-Type: application/json" \
141+
-d '{
142+
"amount": 29.99,
143+
"isAdjusted": true
144+
}' \
145+
"http://127.0.0.1:8080/1.0/kb/payments/{paymentId}/refunds"
146+
----
147+
148+
*Expected result:* The payment gateway processes the refund. Kill Bill adjusts the corresponding invoice by the refund amount.
149+
150+
=== Refund without Invoice Adjustment
151+
152+
When `isAdjusted` is `false`, only the payment is refunded — the invoice balance remains unchanged. This creates an account balance that needs to be settled.
153+
154+
[source,bash]
155+
----
156+
curl -v -X POST \
157+
-u admin:password \
158+
-H "X-Killbill-ApiKey: my-tenant" \
159+
-H "X-Killbill-ApiSecret: my-secret" \
160+
-H "X-Killbill-CreatedBy: admin" \
161+
-H "Content-Type: application/json" \
162+
-d '{
163+
"amount": 29.99,
164+
"isAdjusted": false
165+
}' \
166+
"http://127.0.0.1:8080/1.0/kb/payments/{paymentId}/refunds"
167+
----
168+
169+
*Expected result:* The payment gateway processes the refund. The invoice balance is not changed — the account shows an outstanding balance equal to the refund amount.
170+
171+
== Impact on Aviate Features
172+
173+
=== Tax
174+
175+
Refunded or voided invoice items may require tax adjustment. If the original invoice included tax items generated by Aviate Tax, the adjustment or void reverses the charge but does *not* automatically reverse the tax item. Check your tax logic configuration to determine whether a separate tax adjustment is needed. See https://docs.killbill.io/latest/aviate-tax.html[Tax Configuration].
176+
177+
=== Revenue Recognition
178+
179+
Credits and refunds trigger revenue reversals in the recognition schedule. If Aviate revenue recognition is enabled, invoice adjustments and voids will create corresponding reversal entries in the revenue recognition report.
180+
181+
=== Wallet
182+
183+
Kill Bill account credits are *completely separate* from Aviate wallet credits:
184+
185+
* Adding a KB account credit does *not* increase the wallet balance.
186+
* Refunding a payment does *not* restore wallet credits that were consumed.
187+
* Voiding an invoice that consumed wallet credits does *not* automatically return credits to the wallet.
188+
189+
If you need to restore wallet credits, you must manually add credits back to the wallet via the Aviate wallet API. See https://docs.killbill.io/latest/aviate-wallet.html[Wallet Guide].
190+
191+
=== Metering
192+
193+
Adjusting a `USAGE` invoice item corrects the financial record but does *not* reverse the underlying metering events. The usage events remain in Kill Bill's usage store. If you need to correct metering data, use the Aviate metering APIs separately. See https://docs.killbill.io/latest/aviate-metering.html[Metering].
194+
195+
== What to Verify
196+
197+
After performing credit, refund, or adjustment operations, verify the results:
198+
199+
=== Check Account Balance
200+
201+
[source,bash]
202+
----
203+
curl -v \
204+
-u admin:password \
205+
-H "X-Killbill-ApiKey: my-tenant" \
206+
-H "X-Killbill-ApiSecret: my-secret" \
207+
"http://127.0.0.1:8080/1.0/kb/accounts/{accountId}"
208+
----
209+
210+
Look for the `accountBalance` and `accountCBA` (credit balance adjustment) fields.
211+
212+
=== Check Invoice Details
213+
214+
[source,bash]
215+
----
216+
curl -v \
217+
-u admin:password \
218+
-H "X-Killbill-ApiKey: my-tenant" \
219+
-H "X-Killbill-ApiSecret: my-secret" \
220+
"http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}?withItems=true"
221+
----
222+
223+
Verify that adjustment items appear and the invoice balance is correct.
224+
225+
=== Check Payment Status
226+
227+
[source,bash]
228+
----
229+
curl -v \
230+
-u admin:password \
231+
-H "X-Killbill-ApiKey: my-tenant" \
232+
-H "X-Killbill-ApiSecret: my-secret" \
233+
"http://127.0.0.1:8080/1.0/kb/payments/{paymentId}"
234+
----
235+
236+
Verify that the refund transaction appears in the payment's transaction list with status `SUCCESS`.
237+
238+
== Common Pitfalls
239+
240+
1. **Confusing Aviate wallet credits with KB account credits** — they are independent systems with different APIs, authentication methods, and behaviors. Review the comparison table above.
241+
2. **Refunding more than the payment amount** — returns an error. The refund amount cannot exceed the original payment amount minus any previous refunds.
242+
3. **Voiding an invoice that has payments** — returns an error. You must refund all payments on the invoice before voiding it.
243+
4. **Adjusting a USAGE invoice item** — corrects the financial record but does not reverse the underlying metering events. Usage data must be corrected separately via Aviate metering APIs.
244+
5. **Credit applied to wrong currency** — returns a `400 Bad Request` error. The credit currency must match the account's currency.
245+
6. **Large credit amounts without approval** — there is no built-in approval workflow for credits. Consider implementing business process controls outside Kill Bill for large credit amounts.
246+
247+
== Related
248+
249+
* https://docs.killbill.io/latest/aviate-wallet.html[Wallet] — Aviate-managed prepaid credits
250+
* https://docs.killbill.io/latest/aviate-subscription-lifecycle.html[Subscription Lifecycle] — plan changes, cancellations, pauses
251+
* https://docs.killbill.io/latest/aviate-tax.html[Tax Configuration] — tax implications of adjustments
252+
* https://docs.killbill.io/latest/aviate-metering.html[Metering] — usage event handling and corrections
253+
* https://docs.killbill.io/latest/aviate-coupons.html[Coupons] — discount behavior with credits

0 commit comments

Comments
 (0)