Create Invoice
The API endpoint for creating an invoice is as follows:
POST /api/v2/invoices
All examples below, use this endpoint. This page gives examples for each of these use cases:
- Create invoice with NEW customer and product information.
- Create invoice with existing customer and product information.
New Customer and Products
Request
curl -X POST https://secure.usaepay.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.usaepay.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.
Existing Customer and Product
Request
curl -X POST https://secure.usaepay.com/api/v2/invoices
-H "Content-Type: application/json"
-H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
-d
'{
"invoice_number": "10-205252",
"due_date": "2018-03-24 19:53:44",
"nontaxable": "N",
"discount": 8,
"tax_rate": 9,
"tip": 0,
"shipping": 10,
"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",
"cust_key": "6sddnk3n3j2wcn3y"
"lineitems": [
{
"product_key": "bs4btxwm1sq7s76n",
}
],
"customdata": {
"custom1": "Custom Field 1",
"custom2": "Custom Field 2"
},
This cURL request is an example of a request to create an invoice using a customer from the database for customer billing information and products from the existing database for line items.
Response
"key": "gskjt8gs38tcb383",
"type": "invoice",
"merch_refnum": "120186",
"status": "Q",
"invoice_number": "10-205252",
"invoice_date": "2018-02-22 19:56:22",
"due_date": "2018-03-24 19:53:44",
"subtotal": "2.00",
"nontaxable": "N",
"discount": "8",
"tax": "0.1800",
"tax_rate": "9",
"tip": "0",
"shipping": "10",
"shipping_taxable": "N",
"amount": "4.1800",
"amountdue": "4.1800",
"amountpaid": "0.00",
"view_url": "https://secure.usaepay.com/invoice\/invoice\/gskjt8gs38tcb383\/yyM2gze6",
"terms": "NET 10",
"footer": "Thank you for your business!",
"notes": "",
"comments": "",
"serverip": "127.0.0.1",
"merchant_email": "merchant.email@test.com",
"merchant_address": "100 Universal City Plaza, Universal City, CA 91608",
"lineitems": [
{
"lineid": "59148",
"product_refnum": "739",
"product_key": "bs4btxwm1sq7s76n",
"sku": "1234567",
"name": "Bishop Android",
"description": "Description",
"cost": "2.00",
"qty": "1",
"taxable": "Y",
"tax_rate": null,
"taxclass": null,
"discount_rate": null,
"discount_amount": null,
"locationid": "3",
"commodity_code": "",
"manufacturer": "Manufacturer Name",
"category": "",
"consignment": "",
"size": "",
"color": "",
"ord": "0",
"allow_override": false
}
],
"transactions": [],
"customdata": {
"custom1": "Custom Field 1",
"custom2": "Custom Field 2"
},
"customer_email": "Ridley.Scott@test.com",
"cust_key": "6sddnk3n3j2wcn3y",
"customerid": "",
"customer_billing": {
"firstname": "Charlotte",
"lastname": "Smith",
"company": "Studio",
"street": "1222 Verdugo Cir",
"street2": "#303",
"city": "Los Angeles",
"state": "CA",
"country": "USA",
"postalcode": "90038",
"phone": "8888888888",
"fax": "7777777777"
},
"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-22 19:56:22",
"modified": "2018-02-22 19:56:22"
}
This is the sample response object sent back from the server.
Parameters
Request
The request parameters are listed below
| Parameter | Required | Type | Description |
|---|---|---|---|
| invoice_number | Required | string | Invoice identifier generated by merchant. Character limit: 25. |
| due_date | date | Date invoice is due. Suggested format: YYYY-MM-NN. |
|
| 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_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. | |
| customer_email | Required | string | Email you would like to send the invoice to. |
| customer_billing | Required | customer_billing | Object which holds the customer's billing address. Only First Name or Last Name OR Company are required. |
| customer_shipping | customer_shipping | Object which holds the customer's shipping address. | |
| merchant_email | Required | string | Email the invoice will be sent from. |
| merchant_address | Required | string | Merchant's street address. _Suggested Format: 100 Universal City Plaza, Universal City, CA 91608 |
| 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. | |
| shipping_taxable | boolean | Denotes if invoice total is taxable. Possible Values: Y or N. Defaults to Y. |
|
| lineitems | Required | lineitems | Object which contains line items. |
| 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. | |
| product_key | string | Gateway generated unique product identifier. Will only be included if the line item is a product from the database. |
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 |
|---|---|---|
| key | string | Invoice identifier generated by gateway. |
| type | string | Will always respond invoice. Denotes the object as an invoice. |
| merch_refnum | integer | Merchant identifier generated by gateway. |
| status | string | Invoice status. When first creating an invoice, the status will be Q (Quote). |
| invoice_date | datetime | Date and time the invoice was created. |
| tax | double | Tax amount calculated from tax rate. |
| subtotal | double | Total before shipping, discounts, tips, and tax are applied. |
| 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. |
| transactions | transactions | Transactions associated with this invoice. |
| 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. |
Errors
| Code | Message | Description |
|---|---|---|
| 49 | Merchant ID Mismatch for record locator key | Invoice does not belong to this merchant |
| 51 | Failed to create 'invoice' due to invalid data | Verify all required fields are included and valid. |
| 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. |