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.