Cancel an invoice
Cancel an invoice if you created it in error. Canceled invoices remain on your system for record-keeping purposes.
If you've created an invoice in error, you can cancel it to say that it's no longer needed.
How it works
Invoices work using manually-collected transactions. These are transactions where the collection_mode
is set to manual
, which means that Paddle sends an invoice that customers must pay themselves by bank or wire transfer or using Paddle Checkout.
You can change the status of a manually-collected transaction to canceled
to mark it as canceled. When you cancel an invoice:
- It's no longer due, so customers don't need to pay it
- Links to pay the invoice using Paddle Checkout no longer work
- It doesn't count as revenue for your reports
- You can't un-cancel it, or make any other changes to it
You can cancel manually-collected transactions that are billed
(issued invoices) or ready
. If a transaction is completed
, meaning a customer has paid an invoice, you can create an adjustment to refund all or part of it instead.
Credit an invoice
You might be able to correct some errors on an issued invoice by creating a credit rather than canceling it.
For example, if you create and issue an invoice then want to remove an item, you can create an adjustment for the item you'd like to remove. Paddle automatically applies the credit to the issued invoice, so the amount the customer owes is reduced.
When you credit the full value of a transaction, it's marked as completed
. It's no longer due.
Cancel an invoice
Update the status of a manually-collected transaction to canceled
to cancel an invoice.
Build request
In your request body, include status
and set to canceled
. You don't need to include any other information.
1231{
2 "status": "canceled"
3}
Send request
Send a PATCH request to the /transactions/{transaction_id}
endpoint, passing the Paddle ID of the transaction entity that you'd like to cancel.
Paddle ID of the transaction entity to work with.
Transactions must be manually-collected and
billed
orready
to cancel them. You can get transactions that match by using the list transactions operation, passingcollection_mode=manual
andstatus=billed,ready
Response
If successful, Paddle responds with a copy of the updated transaction entity. The transaction status is canceled
.
12345678910111213141516171819201{
2 "data": {
3 "id": "txn_01j5dx3yajy2hc1p1xz808m92j",
4 "status": "canceled",
5 "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
6 "address_id": "add_01hv8gq3318ktkfengj2r75gfx",
7 "business_id": null,
8 "custom_data": null,
9 "origin": "api",
10 "collection_mode": "manual",
11 "subscription_id": null,
12 "invoice_id": null,
13 "invoice_number": null,
14 "billing_details": {
15 "enable_checkout": false,
16 "payment_terms": {
17 "interval": "day",
18 "frequency": 14
19 },
20 "purchase_order_number": "PO-123",
Cancel related subscription
Paddle automatically creates a subscription when you mark a manually-collected transaction as billed
.
When you cancel an invoice, its related subscription is not automatically canceled. This means the subscription remains active, so a customer may still have access to your app. Paddle reinvoices for the subscription on renewal.
Cancel using the Paddle dashboard or API
Use the Paddle dashboard or API to cancel the related subscription after you have canceled the transaction.
Build a workflow using webhooks
You can build a workflow to programmatically cancel subscriptions using webhooks:
Subscribe to transaction canceled events
Create or update a notification destination, then subscribe to
transaction.canceled
events.Check that the transaction is manually-collected and for a subscription
In the
data
payload for received events, check thatcollection_mode
ismanual
and thatsubscription_id
is notnull
. This means the transaction is an issued invoice related to a subscription.Extract subscription ID, then cancel
Extract
subscription_id
from the data payload, then use the cancel a subscription operation to cancel.
Common errors
transaction_invalid_status_change | Transaction is not billed or ready . |
transaction_immutable | Transaction is completed . Create an adjustment instead. |
Events
transaction.canceled | Occurs when a transaction is canceled. |