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.usaepay.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.usaepay.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.usaepay.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.usaepay.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.usaepay.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.usaepay.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.usaepay.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.usaepay.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.

Click here for the full REST API change log.