Do you want your users to be able to generate invoices directly from your Bubble app? In this article we'll show how you can do exactly that with PDF Potion.
Contents
Database structure
The exact structure of your Bubble database will depend on your app, but we typically recommend including the following two data types and associated custom fields for generating invoices:
Invoice: the overall invoice that contains details on the customer's purchase
- Customer Name (text) - the name of the Customer the invoice is being sent to
- Link (text) - a URL link to a PDF of the invoice
- Invoice Items (list of Invoice Items) - see below
Here's how this looks in an actual Bubble app:
Invoice Item: contains details on line items within each invoice
- Description (text) - a description of the product/service being sold
- Quantity (number) - the number of the product/service that was sold
- Total (number) - the total cost of the product/service
- Unit Price (number) - the unit cost of the product/service
Here's how this looks in an actual Bubble app:
Designing your Invoice
We're going to design our invoice in a separate page of our Bubble app. This page will exist solely so we can use it as a template to generate PDFs of invoices - your users should never actually see this page.
Next, you're going to want to design your invoice on this page. You can design it any way you like, but you will need to:
- Set the type of data on the page to be 'invoice'
- Include a repeating group with the 'Type of content' set to 'Invoice Item' and use 'Current page's Invoice's Invoice Items' as the 'Data source'
Here's an example of an invoice page might look:
Note: You can add this invoice design to your own Bubble app using our free Simple Invoice template.
Setting the dimensions of your invoice page
When generating a PDF of the invoice using PDF Potion, you will have option of selecting a page format (A4, A2, Letter etc.) To ensure the design of your invoice page matches the output PDF, it is recommended to set the dimensions of the main container group on your invoice page to be equal to the dimensions of the PDF you're creating.
For example, if you're creating a Letter-sized PDF in portrait mode, you would set the width of the main container group that contains all the other elements to be equal to 816px. You can see a full list of recommended dimensions for different formats here.
Creating the invoice in your database
Now that the invoice page is designed, you'll need to actually create the 'Invoice' and associated 'Invoice Items' in your database. This may be something you've already integrated into your app, but if not, our Simple Invoices template has an example of how you can do so.
Each time the page is loaded, a new 'Invoice' is created in the database:
When the user clicks on the 'Add Invoice Item' button, a popup is displayed where the user can provide info on a new Invoice Item. This new Invoice Item is then added to the list of Invoice Items on the Invoice.
We now have a new Invoice in our database with an Invoice Item attached to it:
The invoice itself can be viewed by going to the 'invoice' page we designed and appending the unique ID of the Invoice to the end of the page URL:
Now that we've designed our invoice and added the relevant data, it's time to get our invoice generator up and running and start creating PDFs.
Generating a PDF of the invoice
Installing PDF Potion
We're going to use PDF Potion to create a PDF of our invoice page. To get started with PDF Potion, you'll need to:
- Install the PDF Potion plugin from the Bubble plugin marketplace
- Register for an account on the PDF Potion website
- Generate an Access Token in the 'My Account' section of your PDF Potion dashboard
- Paste the Access Token into the 'Access Token' and 'Access Token - dev.' fields in the plugins tab of your Bubble editor
You can read steps #1 and #2 of our quickstart guide for more details on installing PDF Potion.
Building the PDF generation workflow
To create a PDF of the invoice, add a button to the page in your Bubble app where users will initiate the PDF generation. Create a new workflow for this button and include the 'Create PDF' action provided by the PDF Potion plugin. This may be on the same page as the workflow where you earlier created the Invoice and Invoice Items. In our example below, we've added the 'Create PDF of Invoice' button just below where we add the Invoice Items.
There are a whole range of fields that come with the 'Create PDF' action. We don't need to fill out every one, but there are a few key fields that are mandatory.
- Website Home URL: Add the dynamic expression 'Website home URL.
- Page Name: Enter the name of the page where your PDF design is located (in our case this will be the 'invoice' page). You will also need to add the unique ID associated with the Invoice to the end of the Page Name field. In our example we've added the Invoice as custom state and are referencing it via a dynamic expression.
- Identifier: This is the same unique ID that we're adding to the end of the Page Name field
At this point, Bubble will be flagging an issue because the 'Callback URL' field is empty (we'll come to this shortly). However, you can still proceed with generating the PDF.
Click the button with the workflow attached, then go to the 'File Manager' section within the Database tab of your Bubble editor. You should see the generated PDF of the invoice there. Note that it may take a few seconds for PDF Potion to process and upload the PDF, so refreshing your browser might be necessary.
If you click on the file name, you'll be able to see your beautiful invoice PDF in the browser!
Linking the PDF to the 'Invoice' in the database
Next, you'll need to link the PDF of the invoice to an entry in your database so that users can actually download it (or if you want to send it to them by email). This is where the Callback URL field on the 'Create PDF' action comes into play.
To use the Callback URL, you must first enable backend workflows in your Bubble editor by navigating to:
Settings -> API -> check the 'Enable Workflow API and backend workflows' option
NOTE: you will need to be on a paid Bubble plan to do this
Go to the backend workflows section of your Bubble editor and create a new API workflow (in the example below, we've called ours 'get_invoice'). Add in two keys:
- id (type text)
- link (type text)
You MUST use the exact spelling specified above for these two keys.
Add an action to the workflow that updates an Invoice. Filter for the first item where the unique ID matches the key ID being passed through. This ensures you're targeting the first (and only) Invoice in the database with a unique ID equal to the key ID.
Set the 'Link' field of the Invoice to the value of the 'link' key.
This API workflow needs to be triggered each time a PDF of the invoice created. To to this, we can simply add the URL associated with the API workflow as the Callback URL in the 'Create PDF' action. To get the correct URL for it, you can go to:
Settings -> API
and copy the 'Workflow API Root URL' value:
Paste this value into the 'Callback URL' field of the 'Create PDF' action, then append the name of your backend workflow to the end. Next, replace all text before 'api...' with the dynamic expression 'Website home URL'. The final result will look something like this:
Run the 'Create PDF' action again and you should see a URL that links to your PDF for each 'Invoice' entry in your database:
Downloading the PDF
To allow users to download their PDFs, create a custom event on the page where the PDFs are generated. In the example below, the custom event is named 'Invoice Generated'. Add a parameter to the custom event, such as 'Invoice', and set its data type to match the custom data type associated with the PDF link.
Add the 'Download PDF' action to the workflow. Set the 'link' field to 'Report's Link (or your designated custom data type and link field) and specify the desired file name:
Add the 'Download PDF' action to the workflow. Set the 'link' field to Invoice's Link (or the corresponding custom data type and link field), and specify the preferred file name.
Make sure the custom event is triggered whenever a PDF is generated by including a 'Trigger custom event when data changes' action in the original workflow containing the 'Create PDF' action.
Set the 'Thing to watch' to the Invoice (or the equivalent custom data type you're using) and the 'Field to watch' to Link (or the field where the PDF URL is stored).
This ensures that when the Link field is updated with the PDF's URL, the PDF will automatically download in the user's browser.
Now when a user creates a PDF of the invoice, it should be automatically downloaded in their browser:
Note: You'll notice in the GIF above that we're showing a loading screen while the PDF generation is occurring. It can take a few seconds to generate the PDFs, so the loading screen gives the user an indication that work is happening and helps avoid confusion.
You can read this doc on how to add a loading screen while a PDF is being generated.
Sending the invoice via email
If you would prefer to send the invoice to the customer via email instead of having the user download it in their browser, you can add a 'Send email' action to the 'Invoice Generated' custom event (and delete the action where the user downloads the PDF).
The invoice will be sent as an attachment to the email address you specify:
Further Resources
