Skip to main content
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:
FieldDescriptionFormat
clientIdId of the client being invoicedNumeric
invoiceTermLength 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”
lineItemsList of line items to be invoicedSee below
Each line item can include the following fields:
FieldDescriptionFormat
quantityQuantity for the line item (or number of hours)Numeric, up to two decimal places (e.g. 2.50)
priceUnit price of the line item (or price per hour)Numeric (e.g. 100.00)
descriptionDescription of the line itemAny string
expenseIdOptional; 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:
FieldDescriptionFormat
invoiceDateDate displayed on the invoice; also used for double-entry accounting purposes. Defaulted to the current date.”YYYY-MM-DD”, e.g. “2021-06-15”
dueDateDue date for the invoice; required if invoiceTerm is set to “OTHER""YYYY-MM-DD”, e.g. “2021-07-14”
discountAmountThe 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
discountPercentThe 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
invoiceFrequencyInvoice 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.
reminderScheduleAutomatic payment reminder frequenciesArray 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.
emailEmail to send the invoice to. Defaulted to the email associated with the clientWell-formatted string
ccEmailsEmails that should be cc’ed when the invoice is sent to the clientArray of strings
bccEmailsEmails that should be bcc’ed when the invoice is sent to the clientArray of strings
personalNotePersonalized invoice message, to be appended at the end of the invoiceAny 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 api@tight.com 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
  }'