Invoices
- Matt Bryant (Unlicensed)
- Joel Kearney
- Joel Morgan Kearney (Unlicensed)
- Lucy Barber (Unlicensed)
These are the endpoints that are available under the /invoices path, which lists all the invoices on your business' account.
| Endpoint | Description |
|---|---|
| GET /invoices/status/{statusString} | Returns all invoice objects for the given status parameter in array format. The statusString has acceptable values OPEN, CLOSED, and VOID. |
| GET /invoices/{invoiceId} | Returns specified invoice object. |
| GET /invoices/client/{clientId} | Returns an array of all invoice objects connected to specified client. |
| POST /invoices | Creates a new invoice object. The invoiceId value will be set by the server after the POST is received. Request body/payload: Must pass an invoice object in request body/payload. For these calls, you need to pass an invoice object with all required fields and any fields you want to set filled in the body of the payload. We have an example of an invoice object in the responses section below and have indicated the required fields in the object values table at the bottom of this page. |
| POST /invoices/client/{clientId} | Creates an invoice for specified client with invoice line items already in it. Request body/payload: Must pass an array of invoice item objects in request body/payload. For these calls, you need to pass an invoice object with all required fields and any fields you want to set filled in the body of the payload. We have an example of an invoice object in the responses section below and have indicated the required fields in the object values table at the bottom of this page. |
| PUT /invoices | Updates an invoice object. To update status, set the status field to one of the other status options (OPEN, CLOSED, VOID) and set the subStatus field to "Manual". Request body/payload: Must pass an invoice object in request body/payload-make sure to include the correct invoiceId. For these calls, you need to pass an invoice object with all required fields and any fields you want to update filled in the body of the payload. We have an example of an invoice object in the responses section below and have indicated the required fields in the object values table at the bottom of this page. |
| DELETE /invoices/{invoiceId} | Removes an invoice object from view by setting its active property to false. |
Data points passed on in the request URL portion of the API call that are used to filter the data being requested. To aid with page load time, we use pagination parameters that can be passed with your GET request. All parameters for invoice calls are optional.
| Parameter | Type | Endpoints to be used with | Description |
|---|---|---|---|
| chargeEndDate | string | GET /invoices/status/{statusString} | Should be set as the end date of invoices to be returned following the GET call when you opt to organize them by charge date, formatted as YYYY-MM-DD. |
| chargeStartDate | string | GET /invoices/status/{statusString} | Should be set as the start date of invoices to be returned following the GET call when you opt to organize them by charge date, formatted as YYYY-MM-DD. |
| invoiceEndDate | string | GET /invoices/status/{statusString} | Should be set as the end date of invoices to be returned following the GET call when you opt to organize them by invoice date, formatted as YYYY-MM-DD. |
| invoiceStartDate | string | GET /invoices/status/{statusString} | Should be set as the start date of invoices to be returned following the GET call when you opt to organize them by invoice date, formatted as YYYY-MM-DD. |
| invoiceType | string | POST /invoices/client/{clientId} | Should be set as the invoice type of the invoice you are creating. Acceptable values include INVOICE and QUOTE. |
| order_field | string | GET /invoices/status/{statusString} | Should be set as the field that invoices returned following the GET call should be ordered by. |
| order_mode | string | GET /invoices/status/{statusString} | Should be set as the mode ('asc'ending or 'desc'ending) in which invoices returned following the GET call should appear. |
pageNumber | integer | GET /invoices/status/{statusString} | Works with the pageSize parameter to determine how invoices get returned following the GET call. The pageNumber value represents the number of pages on which the invoices that get returned appear. |
pageSize | integer | GET /invoices/status/{statusString} | Works with the pageNumber parameter to determine how invoices gets returned following the GET call. The pageSize value represents the number of invoices appearing on each page that gets returned. |
The objects below represent the minimum viable objects to pass that are needed to create or update an invoices object. Check whether or not a property can be written to by looking at the Object Values table below to see if the property is writable.
| Property Name | Type | Required | Description |
|---|---|---|---|
| balanceAmount | integer | Displays the monetary amount of the remaining balance for specified invoice. | |
| billingLocationId | integer | Provides unique numerical ID for the location of specified invoice. | |
| billingStaffId | integer | Provides unique numerical ID for the staff of specified invoice. | |
| businessId | integer | Yes | Provides unique numerical ID for the business to which specified invoice belongs. |
| chargeDate | integer | Displays any charge date set on the invoice detail page in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. | |
| client | object | Yes | Displays client object for client of invoice - for more info, see Clients API page. |
| comments | string | Displays any comments added to profile of specified invoice. | |
| createdDate | integer | Displays as date specified invoice was created in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. | |
| createdUser | string | Displays as username of the user who created specified invoice. If client booked appointment from scheduler would display as "WebClient". | |
| currency | string | Displays the currency used for specified invoice in string form. (For US dollars this will show as "USD") | |
| depositAmount | integer | Displays the monetary amount of any deposit paid for specified invoice. | |
| invoiceDate | integer | Yes | Displays as date of specified invoice in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. |
| invoiceDueDate | integer | Displays the due date for specified invoice in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. | |
| invoiceHash | string | Provides unique alphanumeric string that can be used when the invoice is set on a public URL to make it harder to duplicate and hack. | |
| invoiceId | integer | Yes, on PUT calls | Provides unique numeric ID for specified invoice. |
| invoiceItem | array | Displays an array of invoiceItem objects for the different invoices on your account. | |
| invoiceNumber | string | Provides an optional string property that you can set on POST or PUT calls. | |
| invoiceType | string | Yes | Displays the type for specified invoice. Has acceptable values INVOICE, TRANSFER_IN, and TRANSFER_OUT. For more information on invoices of type TRANSFER_IN and TRANSFER_OUT, see Products API page. |
| lastStatusDate | integer | Displays the date status was last modified in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. | |
| location | object | Displays location object for location of invoice - for more info, see Locations API page. | |
| modifiedUser | string | Displays as username of the user who last modified specified invoice. If client modified appointment from scheduler would display as "WebClient". | |
| paidAmount | integer | Displays the amount that has been paid for specified invoice. | |
| paidOnDate | integer | Displays the date on which specified invoice was paid in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. | |
| preAuthPayment | boolean | Indicates whether or not payments made on the invoice are pre-authorized. | |
| staff | object | Displays staff object for staff of invoice - for more info, see Staff API page. | |
| status | string | Displays the status of specified invoice. Has acceptable values OPEN, CLOSED, VOID, and DELETED. | |
| subStatus | string | Displays the substatus of specified invoice. Has acceptable values "No Payment", "Partial Payment", "Paid", "Payment Declined", and "Manual". | |
| subtotalAmount | integer | Displays the subtotal amount for specified invoice. | |
| tax2Amount | integer | If you have to account for two different tax rates, this displays the monetary value taken out for the secondary tax rate. There is no editable field for this property. | |
| taxAmount | integer | Displays the monetary value taken out for taxes based on what you set as your tax rate under Payments. | |
| tipAmount | integer | Displays the monetary amount of any tip included with specified invoice. | |
| transactionFeeAmount | integer | Displays the monetary amount of any transaction fee included with specified invoice. | |
| writeOffAmount | integer | Displays the monetary amount of any write off related to specified invoice. |