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.

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
  }'