Creating an Invoice Draft/Quote

Once you've added your user's client, you're now ready to create a draft invoice!

1. Creating the draft invoice

There are several required fields when creating a draft invoice:

Field	Description	Format
clientId	Id of the client being invoiced	Numeric
invoiceTerm	Length of time give to client to pay the invoice amount; if a custom date is desired, use "OTHER"	Must be one of the following: "DUE_NOW", "NET_10", "NET_15", "NET_30", "NET_60", "OTHER"
lineItems	List of line items to be invoiced	See below

Each line item can include the following fields:

Field	Description	Format
quantity	Quantity for the line item (or number of hours)	Numeric, up to two decimal places (e.g. 2.50)
price	Unit price of the line item (or price per hour)	Numeric (e.g. 100.00)
description	Description of the line item	Any string
expenseId	Optional; Id of the expense being invoiced/reimbursed, if using Expense Tracking. When used, relevant receipts are automatically attached, and appropriate journal entries are automatically created.	String

Optional data parameters, for more advanced invoicing functionality, are listed below:

Field	Description	Format
invoiceDate	Date displayed on the invoice; also used for double-entry accounting purposes. Defaulted to the current date.	"YYYY-MM-DD", e.g. "2021-06-15"
dueDate	Due date for the invoice; required if invoiceTerm is set to "OTHER"	"YYYY-MM-DD", e.g. "2021-07-14"
discountAmount	The total dollar amount to be discounted (you can provide a discountAmount or a discountPercent, but not both, as it affects the visual layout of the invoice)	Numeric; e.g. 100.00
discountPercent	The total percent to be discounted (you can provide a discountAmount or a discountPercent, but not both, as it affects the visual layout of the invoice)	Numeric, e.g. 10.00, which means the client will be given a 10% discount
invoiceFrequency	Invoice frequency; useful for recurring invoices. Defaulted to ONE_TIME.	Must be one of the following: ONE_TIME, WEEKLY, BI_WEEKLY, MONTHLY, YEARLY or AFTER_TWO_MINS Note that "AFTER_TWO_MINS" is solely for dev/testing purposes.
reminderSchedule	Automatic payment reminder frequencies	Array of strings, which can be any of the following values: "ON_DUE_DATE", "THREE_DAYS_AFTER_DUE_DATE", "EVERY_SEVEN_DAYS_AFTER_DUE_DATE", "AFTER_TWO_MINS". Note that "AFTER_TWO_MINS" is solely for dev/testing purposes.
email	Email to send the invoice to. Defaulted to the email associated with the client	Well-formatted string
ccEmails	Emails that should be cc'ed when the invoice is sent to the client	Array of strings
bccEmails	Emails that should be bcc'ed when the invoice is sent to the client	Array of strings
personalNote	Personalized invoice message, to be appended at the end of the invoice	Any string

To add the draft invoice, simply POST the invoice's JSON object to the /invoice endpoint:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/invoicing/invoice \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "invoice": {
      "clientId": 805609,
      "invoiceDate": "2021-07-27T00:00:00.000Z",
      "invoiceTerm": "NET_30",
      "lineItems": [
        {
          "quantity": 2,
          "price": "100",
          "description": "Storyboarding"
        }, {
          "quantity": 2,
          "price": "100",
          "description": "Wireframe Designs"
        },
      ]
    }
  }'

2. Generating an invoice preview

The response from POST /invoice contains the invoice's id, which you should store in your database.

{
    "result": "SUCCESS",
    "invoiceId": "21850"
}

To generate a preview for that invoice (e.g. to display to your user, embed in your UI, etc), you should make the following POST:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/invoicing/previewInvoice \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": 21850
  }'

The response will contain an htmlReport attribute, which contains an embeddable HTML body of the user's invoice, including their custom branding that you set up earlier:

{
    "result": "SUCCESS",
    "htmlReport": "<html> Your user's invoice draft's html </html>",
    "invoiceId": "21850",
}

You can parse out the htmlReport field and embed that in your product's UI for your user to review.

3. Sending a quote to your user's client

You can also email a quote to the client. Once you have obtained an invoiceId, you can simply POST that to the /sendInvoice endpoint as follows, and it will send the quote to the emails associated with that invoice's client record. The email will contain a PDF attachment, with "DRAFT" watermarked across it. If you'd like these emails to originate from your own domain, simply email [email protected] and our API team will work with you to set that up.

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/invoicing/sendInvoice \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "invoiceId": 21850
  }'

4. Updating a draft

You can make updates to a draft invoice by simply repeating the initial POST to the /invoice, and including the invoice's id:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/invoicing/invoice \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": 21850
    "clientId": 805609,
    "invoiceDate": "2021-07-27T00:00:00.000Z",
    "invoiceTerm": "NET_30",
    "lineItems": [
      {
      	"quantity": 2,
        "price": "100",
        "description": "Storyboarding"
      }, {
      	"quantity": 2,
        "price": "100",
        "description": "Wireframe Designs"
      },
    ],
    "discountAmount": 50.00
  }'