Corrupt PDFs on Emailed ConnectWise Invoices: Why It Happens and What to Do
Overview
A customer tells you the invoice PDF you emailed them won’t open. Or it opens to a blank page, or half an invoice. You resend it and it’s fine, or it isn’t. If you email custom ConnectWise invoices built in Report Writer, especially in large batches, you’ve probably seen this.
In this post I’ll go over what’s usually going on behind corrupt or incomplete invoice PDFs, what you can realistically do about it inside Report Writer, and how a hosted invoice generator solves the problem.
What It Looks Like
- Some invoices in an emailed batch open fine and others come through as a damaged or empty PDF.
- The same invoice sent again on its own works.
- It happens more at billing time, when many invoices go out at once, and more with longer or more complex invoice designs.
- Nothing is wrong with the invoice data or the template. Reprinting one at a time looks perfect.
That last point is the tell. If a single invoice renders correctly by itself, the template isn’t the problem. The problem is what happens when the system is asked to render a lot of them, or a heavy one, within a limited amount of time.
What’s Going On
A custom Report Writer invoice is rendered on demand by the ConnectWise cloud. Each render takes a certain amount of time and resources, and that grows with the size of the invoice: more line items, more time entries, more agreement detail, more subreports. Print or email a stack of them at once and you’re asking for many of those renders in parallel. When one runs out of time or gets cut off, what lands in the email can be a truncated file instead of a clean error.
The result looks random because it depends on how busy the system was at that moment and how heavy that particular invoice was. It also tends to happen the most for cloud partners, especially at the beginning and end of the month, when many people are also doing invoicing and stressing the ConnectWise cloud servers.
What You Can Do in Report Writer
Honestly, not much, and ConnectWise’s own guidance comes down to two things:
- Make the invoice simpler. Fewer subreports, fewer detail sections, less conditional logic. This helps, but it’s a trade you may not want to make, since the detail is usually why you built a custom invoice.
- Don’t print or email too many at once. Send in smaller batches. This also helps, but it makes the billing cycle more cumbersome.
Neither fixes the cause. They just make you less likely to hit it, and you still have to find the bad ones by hearing from a customer because ConnectWise will not usually give you an error message to indicate that anything is wrong.
How a Hosted Generator Handles It
With hosted invoice templates, the PDF isn’t rendered inside ConnectWise’s reporting engine at all. The invoice link in ConnectWise points to a generator that pulls the invoice data through the ConnectWise API and renders the PDF itself. That moves the failure modes somewhere you can actually do something about them. Two things matter most.
429 Back Off
The ConnectWise API limits how many requests you can make in a short period. When you go over, it answers with a 429 (too many requests), and usually tells you how long to wait. A single invoice needs several API calls: the invoice, its line items, time entries, expenses, the agreement. A batch of invoices multiplies that quickly.
A well behaved client doesn’t give up on a 429, and doesn’t hammer the API harder either. It waits as long as ConnectWise says to, with a short random delay so a whole batch doesn’t retry at the same instant, and then tries again. The invoice takes a few seconds longer to come back, but it comes back complete. There’s also a ceiling on how many calls one invoice is allowed to make, so a mistake in a template can’t turn into thousands of requests and get your whole ConnectWise API locked out.
Caching
Once an invoice has been rendered, you can store the PDF somewhere that your invoice tool can retrieve quicker the next time. The next request for the same invoice with the same template and settings returns the stored PDF straight away, with no ConnectWise API calls and no rendering. That has a few practical effects:
- Resending an invoice, or a customer clicking the link twice, costs nothing.
- If a big batch hits a limit partway through, a retry only has to render the ones that didn’t finish. The finished ones are already cached. The retry can happen in the background during the invoice batch so, to your invoicing person, this is just a small delay.
- If the invoice is edited in ConnectWise, the change is detected and it renders fresh, so you don’t serve a stale copy.
Problems to Watch For
- Test with a real batch, not one invoice. A single invoice will look fine on any system. Send a stack of your largest invoices at month end volume. We have clients that send hundreds of invoices at a time without issue.
- Check the invoice that always fails. If it’s the same one every time, it may be a data problem (a very large time entry list, an unusual character) and not volume. You may need to build in some data transformation in your Report Writer or API template tool to address it.
If you’re also thinking about how those invoices get out the door, see a billing portal to review, combine, send and close ConnectWise invoices, and combining ConnectWise invoices.
Want to Stop Hearing About Corrupt PDFs?
If you’re tired of resending custom invoices and explaining to customers why the PDF wouldn’t open, see how NexNow hosted invoices work, or book a demo and we’ll run some of your own invoices through it.
