Search Invoices
The GET invoices endpoint allows you to search for a specific invoice, a list of all invoices, or filter invoices using preset filters. You will find endpoints, parameters, and examples for all below.
Get Invoice
The API endpoint for searching for one particular invoice is as follows
GET /api/v2/invoices/:key:
Request
curl -X GET https://secure.newtekgateway.com/api/v2/invoices/7skjkdcxz7800mz3
-H "Content-Type: application/json"
-H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
This cURL request is an example of a request to retrieve a specific invoice.
Response
{
"key": "7skjkdcxz7800mz3",
"type": "invoice",
"merch_refnum": "120186",
"status": "Q",
"invoice_number": "632538",
"invoice_date": "2018-02-22 17:04:25",
"due_date": "2018-03-24 17:03:30",
"subtotal": "99.00",
"nontaxable": "N",
"discount": "8.00",
"tax": "2.61",
"tax_rate": "9.00",
"tip": "0.00",
"shipping": "10.00",
"shipping_taxable": "N",
"amount": "103.61",
"amountdue": "103.61",
"amountpaid": "0.00",
"view_url": "https://secure.newtekgateway.com/invoice\/7skjkdcxz7800mz3\/XNXfLtVQ",
"terms": "NET 10",
"footer": "Thank you for your business!",
"notes": "Already paid downpayment.",
"serverip": "127.0.0.1",
"merchant_email": "merchant.email@test.com",
"merchant_address": "100 Universal City Plaza, Universal City, CA 91608",
"lineitems": [
{
"lineid": "59010",
"product_refnum": null,
"product_key": null,
"sku": null,
"name": "Custom Item 1",
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"cost": "14.50",
"qty": "2",
"taxable": "Y",
"tax_rate": "9.000",
"taxclass": null,
"discount_rate": null,
"discount_amount": null,
"locationid": "0",
"commodity_code": "A",
"manufacturer": "B",
"category": "C",
"consignment": "Y",
"size": "123",
"color": "red",
"ord": "1"
},
],
"transactions": [],
"customdata": {
"custom1": "Custom Field 1",
"custom2": "Custom Field 2",
"custom3": "Custom Field 3",
"custom4": "Custom Field 4",
"othercustom": "Other Custom 1",
"otherwat": "Other Custom 2",
"idowhatiwant": "Other Custom 3"
},
"customer_email": "Liam.Wilson@test.com",
"cust_key": 0,
"customerid": "",
"customer_billing": {
"firstname": "Liam",
"lastname": "Wilson",
"company": "Company Name",
"street": "2301 Highland Ave",
"street2": "STE #9",
"city": "Los Angeles",
"state": "CA",
"country": "USA",
"postalcode": "90068",
"phone": "(555) 555-5555",
"fax": "(555) 555-5555"
},
"customer_shipping": {
"firstname": "Griffin",
"lastname": "Smith",
"company": "Other Company Name",
"street": "1000 Vin Scully Ave",
"street2": "STE #9",
"city": "Los Angeles",
"state": "CA",
"country": "USA",
"postalcode": "90012",
"phone": "(555) 555-5555"
},
"sentdate": "",
"created": "2018-02-22 17:04:25",
"modified": "2018-02-22 17:04:25"
}
This is the sample response object sent back from the server.
Parameters
Request
The request parameters are listed below
Parameter | Type | Description |
---|---|---|
key | Invoice identifier generated by gateway. |
Response
Below are the response parameters. Please note: if the parameter was defined in the request parameters above, they are not included in the table below.
Parameter | Type | Description |
---|---|---|
type | string | Will always respond invoice . Denotes the object as an invoice. |
merch_refnum | integer | Merchant identifier generated by gateway. |
status | string | Invoice status. Possible Values: Q - Quote, S - Sent, C - Cancelled, S - Sent, P - Paid, V - Viewed. Click here for explanation of invoice statuses. |
invoice_number | string | Invoice identifier generated by merchant. Character limit: 25. |
invoice_date | datetime | Date and time the invoice was created. |
due_date | date | Date invoice is due. Suggested format: YYYY-MM-NN . |
subtotal | double | Total before shipping, discounts, tips, and tax are applied. |
nontaxable | boolean | Denotes if invoice total is taxable. Possible Values: Y or N . Defaults to N . |
discount | double | Discount applied to total transaction by amount. |
tax | double | Tax amount calculated from tax rate. |
tax_rate | double | Tax percentage that should be applied to transaction amount. |
tip | double | Tip that should be added to invoice by amount. |
shipping | double | Amount that should be added for shipping. |
shipping_taxable | boolean | Denotes if invoice total is taxable. Possible Values: Y or N . Defaults to Y . |
amount | double | Total amount. amount = lineitem totals - (discount + shipping + tax) |
amountdue | double | Amount customers still owes. |
amountpaid | double | Amount customers has already paid. |
view_url | string | URL sent to customer to view invoice. |
terms | string | Terms for the invoice. Click here for examples of common terms. Defaults to terms in invoice settings. |
footer | string | Message to show at the bottom of invoice. Defaults to footer in invoice settings. |
notes | string | Message to show at the bottom of a single invoice and in the email which you send to the customer. |
serverip | string | The ip address the invoice is being sent from. |
merchant_email | string | Email the invoice will be sent from. |
merchant_address | string | Merchant's street address. Suggested Format: 100 Universal City Plaza, Universal City, CA 91608 |
lineitems | lineitems | Object which contains line items. |
transactions | transactions | Transactions associated with this invoice. |
customdata | customdata | Custom fields. |
cust_key | string | Customer identifier generated by gateway. Will only populate if the invoice was sent to an existing customer in the database. |
custtomerid | string | Customer identifier generated by the merchant. Will only populate if the invoice was sent to an existing customer in the database. |
customer_billing | customer_billing | Object which holds the customer's billing address. |
customer_shipping | customer_shipping | Object which holds the customer's shipping address. |
sentdate | datetime | Date and time the invoice was sent. |
created | datetime | Date and time the invoice was created. |
modified | datetime | Date and time the invoice was last modified. |
Get Invoice List
The API endpoint for searching for a list of all invoices is as follows
GET /api/v2/invoices
Please Note: This list will NOT include cancelled invoices. To return a list of cancelled invoices, use the preset filter shown here.
Request
curl -X GET https://secure.newtekgateway.com/api/v2/invoices
-H "Content-Type: application/json"
-H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
This cURL request is an example of a request retrieve a full list of invoices on the account.
Response
{
"type": "list",
"limit": 20,
"offset": 0,
"data": [
{
"key": "3skjt164h3nz9683",
"view_url": "https://secure.newtekgateway.com/invoice\/3skjt164h3nz9683\/sjW4APTW",
"invoice_number": "3",
"status": "V",
"invoice_date": "2017-01-06 09:48:41",
"due_date": "2017-02-05 09:48:40",
"subtotal": "109.00",
"nontaxable": "N",
"discount": "8.00",
"tax": "2.61",
"shipping": "15.00",
"amount": "118.61",
"amountdue": "118.61",
"amountpaid": "0.00",
"customer_email": "harper.williams@test.com",
"customer_billing": {
"firstname": "Harper_2",
"lastname": "Williams",
"company": "Company Name"
},
"created": "2017-01-06 09:48:41",
"modified": "2017-07-10 15:08:03"
},
{
"key": "6skjywh7stn2y833",
"view_url": "https://secure.newtekgateway.com/invoice\/6skjywh7stn2y833\/wx3EUdKp",
"invoice_number": "BB622",
"status": "V",
"invoice_date": "2017-01-06 09:48:45",
"due_date": "2017-02-05 09:48:40",
"subtotal": "253.00",
"nontaxable": "N",
"discount": "8.00",
"tax": "22.26",
"shipping": "10.00",
"amount": "277.26",
"amountdue": "277.26",
"amountpaid": "0.00",
"customer_email": "isabellaj@test.com",
"customer_billing": {
"firstname": "Isabella",
"lastname": "Jackson",
"company": "Company Name"
},
"created": "2017-01-06 09:48:45",
"modified": "2017-02-02 17:06:21"
}
],
"total": "2"
}
This is the sample response object sent back from the server.
Parameters
For the request, there are no additional parameters beyond the endpoint.
Response
Below are the response parameters. Please note: if the parameter was defined in the request parameters above, they are not included in the table below.
Parameter | Type | Description |
---|---|---|
type | string | This will always be list for this request, because it returns a list of invoices. |
limit | number | The number of invoice objects that will return per call. Default is 20. |
offset | number | The number of invoice objects the system will skip before beginning to return results. Default is 0. |
data | object | The list of invoices that match the search. |
total | number | Number of invoices that match the search. |
Get Invoice List and Apply Filter
The API endpoint for filtering using preset filters is the following:
GET /api/v2/invoices/?filters=:filter:
You can also combine the filters by chaining one filter after another. Separate each filter with a space:
GET /api/v2/invoices/?filters=:filter1: :filter2:
To see a list of our available filters, click here.
Request
curl -X GET https://secure.newtekgateway.com/api/v2/invoices?filters=@isSent
-H "Content-Type: application/json"
-H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
This cURL request is an example of a request to retrieve a list of invoices with the
@isSent
filter applied.
Response
{
"type": "list",
"limit": 2,
"offset": 0,
"data": [
{
"key": "3skjt164h3nz9683",
"view_url": "https://secure.newtekgateway.com/invoice\/3skjt164h3nz9683\/sjW4APTW",
"invoice_number": "3",
"status": "V",
"invoice_date": "2017-01-06 09:48:41",
"due_date": "2017-02-05 09:48:40",
"subtotal": "109.00",
"nontaxable": "N",
"discount": "8.00",
"tax": "2.61",
"shipping": "15.00",
"amount": "118.61",
"amountdue": "118.61",
"amountpaid": "0.00",
"customer_email": "harper.williams@test.com",
"customer_billing": {
"firstname": "Harper_2",
"lastname": "Williams",
"company": "Company Name"
},
"created": "2017-01-06 09:48:41",
"modified": "2017-07-10 15:08:03"
},
{
"key": "6skjywh7stn2y833",
"view_url": "https://secure.newtekgateway.com/invoice\/6skjywh7stn2y833\/wx3EUdKp",
"invoice_number": "BB622",
"status": "V",
"invoice_date": "2017-01-06 09:48:45",
"due_date": "2017-02-05 09:48:40",
"subtotal": "253.00",
"nontaxable": "N",
"discount": "8.00",
"tax": "22.26",
"shipping": "10.00",
"amount": "277.26",
"amountdue": "277.26",
"amountpaid": "0.00",
"customer_email": "isabellaj@test.com",
"customer_billing": {
"firstname": "Isabella",
"lastname": "Jackson",
"company": "Company Name"
},
"created": "2017-01-06 09:48:45",
"modified": "2017-02-02 17:06:21"
}
],
"total": "2"
This is the sample response object sent back from the server.
Pre-Made Filters
Below is a list of the preset filters and descriptions for each. Please Note: Canceled invoices will only be returned when the @isCanceled filter is used.
Filter | Description |
---|---|
@due5Days | Retrieve list of invoices due in 5 days. |
@due15Days | Retrieve list of invoices due in 15 days. |
@due30Days | Retrieve list of invoices due in 30 days. |
@isCanceled | Retrieve list of canceled invoices. |
@isPaid | Retrieve list of paid invoices. |
@isSent | Retrieve list of sent invoices (invoices with the status of Viewed are also included). |
@isQuote | Retrieve list of invoices with the status of Q . |
@isUnpaid | Retrieve list of unpaid invoices. |
@isOverdue | Retrieve list of invoices that are unpaid and the due date has passed. |
@isNotOverdue | Retrieve list of invoices which are unpaid and are not yet due. |
Errors
Code | Message | Description |
---|---|---|
49 | Merchant ID Mismatch for record locator key | Invoice does not belong to this merchant |
19001 | The field '[field]' is required. | Field is invalid. |
21003 | Access Denied | You do not have the permission to perform this action. |
99999 | Invoice Not Found | The invoice key is incorrect. |
Change Log
Date | Change |
---|---|
2018-04-09 | Corrected parameter names firstname (previously documented as first_name ), lastname (previously documented as last_name ), and postalcode (previously documented as zip ) in the billing_address and shipping address objects of each example. |
2018-02-27 | Added page. |