Invoices
Newtek Gateway's invoicing feature allows merchants to email their customers an invoice and customers to pay those invoices securely online.
The invoices REST API allows you to create, manage, and send invoices. Look at the Create Invoice and Send Invoice sections of this page for a quick start version of those methods.
Additional Methods
For additional examples, use cases, and invoice management tools visit the pages below:
- Create an Invoice
- Managing an Invoices (Send, Cancel, and Mark as Paid)
- Search Invoices
- Delete an Invoice
Create Invoice
The API endpoint for creating an invoice is as follows
POST /api/v2/invoices
Request
curl -X POST https://secure.newtekgateway.com/api/v2/invoices
-H "Content-Type: application/json"
-H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
-d
'{
"invoice_number": "10-349601",
"due_date": "2018-03-08 13:03:17",
"nontaxable": "N",
"discount": 8,
"tax_rate": 9,
"tip": 0,
"shipping": 10,
"customer_email": "Ridley.Scott@test.com",
"customer_billing": {
"firstname": "Ridley",
"lastname": "Scott",
"company": "Weyland-Yutani",
"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": "Sigourney",
"lastname": "Weaver",
"company": "20th Century Fox",
"street": "1000 Vin Scully Ave",
"street2": "STE #9",
"city": "Los Angeles",
"state": "CA",
"country": "USA",
"postalcode": "90012",
"phone": "(555) 555-5555"
},
"merchant_email": "merchant.email@test.com",
"merchant_address": "100 Universal City Plaza, Universal City, CA 91608",
"terms": "NET 10",
"footer": "Thank you for your business!",
"serverip": "127.0.0.1",
"shipping_taxable": "N",
"lineitems": [
{
"name": "Xenomorph",
"description": "Scary alien that will eat you.",
"cost": 49.5,
"qty": 2,
"taxable": true,
"tax_rate": 9,
"commodity_code": "A",
"manufacturer": "HR Giger",
"category": "ET",
"consignment": "Y",
"size": "XX121",
"color": "Black",
"ord": "1"
}
],
"customdata": {
"custom1": "Custom Field 1",
"custom2": "Custom Field 2"
}
}'
This cURL request is an example of a request to create an invoice.
Response
{
"key": "fskjtxydkx3grpz3",
"type": "invoice",
"merch_refnum": "120186",
"status": "Q",
"invoice_number": "10-349601",
"invoice_date": "2018-02-06 13:03:17",
"due_date": "2018-03-08 13:03:17",
"subtotal": "99.0",
"nontaxable": "N",
"discount": "8",
"tax": "8.910",
"tax_rate": "9",
"tip": "0",
"shipping": "10",
"shipping_taxable": "N",
"amount": "109.910",
"amountdue": "109.910",
"amountpaid": "0.00",
"view_url": "https://secure.newtekgateway.com/invoice\/fskjtxydkx3grpz3\/XW0OsvgP",
"terms": "NET 10",
"footer": "Thank you for your business!",
"notes": "",
"serverip": "127.0.0.1",
"merchant_email": "merchant.email@test.com",
"merchant_address": "100 Universal City Plaza, Universal City, CA 91608",
"lineitems": [
{
"lineid": "55215",
"product_refnum": null,
"product_key": null,
"sku": null,
"name": "Xenomorph",
"description": "Scary alien that will eat you.",
"cost": "49.50",
"qty": "2",
"taxable": "Y",
"tax_rate": "9.000",
"taxclass": null,
"discount_rate": null,
"discount_amount": null,
"locationid": "0",
"commodity_code": "A",
"manufacturer": "HR Giger",
"category": "ET",
"consignment": "Y",
"size": "XX121",
"color": "Black",
"ord": "1"
}
],
"transactions": [],
"customdata": {
"custom1": "Custom Field 1",
"custom2": "Custom Field 2"
},
"customer_email": "Ridley.Scott@test.com",
"cust_key": 0,
"customerid": "",
"customer_billing": {
"firstname": "Ridley",
"lastname": "Scott",
"company": "Weyland-Yutani",
"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": "Sigourney",
"lastname": "Weaver",
"company": "20th Century Fox",
"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-06 13:03:17",
"modified": "2018-02-06 13:03:17"
}
This is the sample response object sent back from the server.
More Info
For descriptions of parameters and possible errors, visit the Create an Invoice page.
Send Invoice
Before the customer can view and pay the invoice, you must send the invoice and mark it as sent. The API endpoint for sending an invoice is as follows.
POST /api/v2/invoices/:key:/send
Request
curl -X POST https://secure.newtekgateway.com/api/v2/invoices/fskjtxydkx3grpz3/send
-H "Content-Type: application/json"
-H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
-d
'{
"mark_as_sent": true
}'
This cURL request is an example of a request to send an invoice marked as sent.
Response
{
"status": "success"
}
This is the sample response object sent back from the server.
Parameters
Request
| Parameter | Description |
|---|---|
| mark_as_sent | Setting to true will finalize the invoice. Denotes the invoice has been marked as sent and emailed to the customer. Customer can now use the link provided in the email to pay the invoice. |
Response
| Parameter | Description |
|---|---|
| status | If invoice is sent then status will be returned as success. If invoice is not sent, an error will be returned instead. |
Errors
| Code | Message | Description |
|---|---|---|
| 49 | Merchant ID Mismatch for record locator key | Invoice does not belong to this merchant |
| 3006 | Unable to update Invoice due to current status | Cannot update invoice with cancelled status. |
| 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. |