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:

New Customer and Products

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.

Existing Customer and Product

Request

curl -X POST https://secure.newtekgateway.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.newtekgateway.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.

Click here for the full REST API change log.