Quick Invoices Endpoint
Quick Invoices is a way for a merchant to send an email to a customer with a link to make a payment. This link, when clicked, opens a browser containing the Quick Invoice of whatever it is that the customer purchased. Each Quick Invoice email will have the ability to be customized by the merchant. There will be a default template provided for the merchant as a starting point. Once paid, the customer will receive an email thanking them for their payment. The system will send the customer email notifications prior to the due date, on the due date, and past the due at the discretion of the merchant. There will also be reporting provided to the merchant.
Quick Invoice Process
The detail listed below in this document explains how to use the API to create and update quick invoices. Once an invoice is created, the system will send an email with the details of the quick invoice and a link on how to make a payment towards the invoice.
The email will contain a link that looks something like the following:
When the end user receives this email, they will be able to click on the link and it will take them to a page that looks like the image below. This page is where they will be making their payment(s).
Once a payment is made on the quick invoice, the transaction will show up in the transaction listing with a reference to the quick invoice.
Including File Attachments
It is possible to create a QuickInvoice and attach files to it in a single request. You just need to include all of the normally required fields along with the files and POST this data using multipart/form-data encoding.
The following code examples demonstrate how this can be done across a few different popular languages. You may need to extrapolate the concepts found here to whatever specific solution you are implementing.
For additional information on working with QuickInvoices and file attachments, please take a look at our File Attachments documentation further below on this page.
NOTE: a QuickInvoice cannot be updated if it's already closed,
View Single Record
View Record List
Note: Filters can be used to search for Quick Invoices by including the columns you want to filter on as URL parameters. i.e.
Note: Quick Invoices may only be reopened if:
- Quick Invoice is not deleted
- Quick Invoice is not expired
- Quick Invoice status_id = 0
- Quick Invoice payment_status_id = 1 or 3
- If allow_overpayment is true, then payment_status_id may also be 2
The following request can be used in scenarios where payment for a QuickInvoice was collected through another medium and the transaction needs to be associated with the QuickInvoice so that the remaining balance is updated accordingly.
The following request can be used in scenarios where a Transaction needs to be disassociated from a QuickInvoice.
Resend Notification Email / SMS Notification
There may be times when it is necessary to Resend the Notification Email and/or SMS Notification to the recipient. You can use the following requests to make that happen.
This will resend Email and SMS if both are available, otherwise it will send only the available option.
This will only resend the Email Notification, regardless of any SMS option being available.
This will only resend the SMS Notification, regardless of any Email option being available.
|Name||Min||Max||Format||POST Required||POST Allowed||PUT Allowed||Comments|
|ach_product_transaction_id||24||36||string||✔||✔||✔||ACH product transaction on which QI is created. This field is optional and will default to default_ach product if not supplied at all. Either this or cc_product_transaction_id must be supplied. Changes are allowed on PUT if payments have not been made against QI.|
|active||1||1||boolean||Determines whether the invoice is currently active or not|
|allow_overpayment||1||1||boolean||✔||✔||Will determine if this quick invoice will accept payments after amount due has been met|
|allow_partial_pay||1||1||boolean||✔||✔||Will determine if this quick invoice must be paid in full (0) or will accept partial payments (1)|
|attach_files_to_email||1||1||boolean||✔||✔||If true, any files that are attached to the QuickInvoice will also be included in the QuickInvoice Notification email.|
|amount_due||0||12||decimal(10,2)||This is the amount that need to be paid (automatically calculated by system). amount_due= sum of items in item_list|
|cc_product_transaction_id||24||36||string||✔||✔||✔||CC product transaction on which QI is created. This field is optional and will default to default_cc product if not supplied at all. Either this or ach_product_transaction_id must be supplied. Changes are allowed on PUT if payments have not been made against QI.|
|contact_id||24||36||string||✔||✔||Optional. If the associated
|contact_api_id||1||64||string||✔||✔||Optional. If there is a matching contact in the system, the API will translate this to a
|created_ts||10||10||timestamp||System created timestamp|
|created_user_id||24||36||string||User id who created the Quick invoice|
Required for ACH transactions when Driver's License Verification is enabled on the terminal. Either dl_number + dl_state OR customer_id will need to be passed in this scenario.
Can also be used by Merchants to be able to identify Contacts in our system by an ID from another system.
|dl_number||1||50||string||✔||Required for ACH transactions when Driver's License Verification is enabled on the terminal. Either dl_number + dl_state OR customer_id will need to be passed in this scenario.|
|dl_state||2||2||string||✔||Required for ACH transactions when Driver's License Verification is enabled on the terminal. Either dl_number + dl_state OR customer_id will need to be passed in this scenario.|
|dob_year||4||4||string||✔||Required for certain ACH transactions where Identity Verification has been enabled for the terminal. Either ssn4 or dob_year will need to be passed in this scenario but NOT BOTH.|
|due_date||10||10||date||✔||✔||✔||The date that a Merchant would like a QuickInvoice to be paid by.|
|5||128||string||✔||✔||Optional. An email address that should be used as the "To" address when sending a QuickInvoice Notification email. This can be provided in POST and can be different from an associated Contact's email. If not provided, this field will be backfilled from a Contact if possible.|
|expire_date||10||10||date||✔||✔||Expire date of quickinvoice|
|files||array||✔||An array of files that should be attached to the QuickInvoice.
* Only applicable to multipart/form-data POST requests.
|id||24||36||string||System generated id|
|invoice_number||0||64||string||✔||✔||Invoice number for the quick invoice|
|is_active||1||1||boolean||Whether or not this quick invoice is active|
|item_footer||0||250||string||✔||✔||Item footer used for item_list|
|item_header||0||250||string||✔||✔||Item header used fo item_List|
|item_list||5||4000||string||✔||✔||✔||List of item that quickinvoice hold. This is a json array of items|
|location_id||24||36||string||✔||✔||Location id to which quick invoice belongs to|
|modified_ts||10||10||timestamp||System created timestamp|
|modified_user_id||24||36||integer||User id who modified the quick invoice|
|note||200||string||✔||✔||Used to display a Note from the Merchant to the Quick Invoice Recipient.|
|notification_days_after_due_date||1||2||integer||✔||✔||If set, will cause a QuickInvoice Notification email to be sent 'x' # of days AFTER
|notification_days_before_due_date||1||2||integer||✔||✔||If set, will cause a QuickInvoice Notification email to be sent 'x' # of days BEFORE
|notification_on_due_date||1||1||boolean||✔||✔||Sends notification to email on due_date|
Will be one of:
1 - Unpaid
2 - Paid
3 - Partially Paid
|quick_invoice_api_id||0||64||string||✔||✔||See api_id page for more details|
|remaining_balance||0||12||decimal(10,2)||Upon creation it is same as amount_due; it will tell how much amount left to make a payment and is recalculated each time a payment is made|
If set to
|ssn4||4||4||string||✔||For ACH transactions where Identity Verification is enabled for terminal. Only ssn4 OR dob_year should be passed, not both.|
The various statuses of the quick invoice:
1 - Open
2 - Closed
|title||1||64||string||✔||✔||✔||Title of quick invoice|
Controlling Notification Emails
The following fields are described above, however they are re-listed here in the interest of highlighting those fields that specifically impact if and when QuickInvoice Notification emails should be sent, and how they relate to one another.
|contact_id||Optional. If the associated contact.email field has a value, contact.email will be used to fill
|contact_api_id||Optional. If there is a matching contact in the system, the API will translate this to a contact.id value and save it with the QuickInvoice. If the associated contact.email field has a value, contact.email will be used to fill
|Optional. An email address that should be used as the "To" address when sending a QuickInvoice Notification email.|
|notification_days_before_due_date||Optional. If set, will cause a QuickInvoice Notification email to be sent 'x' # of days BEFORE
|notification_on_due_date||Optional. Possible values:
If set to
|notification_days_after_due_date||Optional. If set, will cause a QuickInvoice Notification email to be sent 'x' # of days AFTER
|due_date||Required. The date that a Merchant would like a QuickInvoice to be paid by. This field is used in comparisons for the notification_*_due_date fields.|
|send_email||Optional. Possible values:
If set to
Expands (Related Records)
For detail on how to use Expands on an Endpoint, please visit the Expands (Related Records) page.
|Related Record||Filter Name|
|Quick Invoice Settings||quick_invoice_settings|
|Quick Invoice Views||quick_invoice_views|
|The url of the actual payment form||payment_url|
An example of “expanding” this endpoint to one of the above related records would look like this:
To use multiple expands on this endpoint, simply include them both separated by a comma like so:
It can be useful to attach files to a Quick Invoice for many different business models, but before getting started there are some items to consider.
File Storage Service
In order to use file attachments with Quick Invoices, the File Storage Service must be enabled for the Location in which the Quick Invoice is being created.
You can use the following request to enable the service:
- A Quick Invoice can have a maximum of 4 file attachments.
- Each file attachment can be a maximum of 5MB in size.
- When provided, file attachments are always made available on the public facing QuickInvoice payment page where the recipient would be take to when clicking the link.
- By default, file attachments are NOT included in any of the QuickInvoice Notification emails. If you want the file attachments to be included then you will need to make sure that quickinvoice.attach_files_to_email is set to 1. This can be done in the Create request or an Update later (would need to make Resend request after Update).
- Some of the API interactions needed to manage files for QuickInvoices will require the using multipart/form-data encoding instead of JSON.
The following example demonstrates how to attach a file to an existing QuickInvoice. If you are interested in uploading files at the same time you are creating the QuickInvoice, take a look at our documentation above for Including File Attachments.
Accessing Quick Invoice Payment Page
The public endpoint for viewing and paying the quickinvoice can utilize the quickinvoice id or the quick_invoice_api_id.
When using the Quick Invoice Id to view the Quick Invoice, the link will look as follows:
When using Quick Invoice API Id to view the Quick Invoice, the link will look as follows, with the locsations id in the URL: