Invoices

The Invoices API is used to access information about the invoices on your business' account, such as the client, amount, and remaining balance connected to them, as well as to create, update, and delete invoices. The Invoices API is connected to the Appointments and Products APIs, as invoices are statements of the services, products, or charges a client has incurred with your business, and it is connected to the Payments API as a client can submit payments to reduce the balance due on an invoice. Since invoices are necessary for your business to collect revenue, it is crucial that you familiarize yourself with how to get and create invoices on your account.

On this page

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.

POST /invoices

{
    "businessId": 43111,
    "client": {Client object for client of invoice - for more info, see Clients API page},
    "createdDate": 1687540672912,
    "createdUser": "JoeSchmo",
    "invoiceDate": "2023-06-23T17:17:28.175Z",
    "invoiceType": "QUOTE" 
}

POST /invoices/client/{clientId}

[
    "active": true,
    "businessId": 43111,
    "calendarId": 128141495,
    "client": null,
    "clientId": 17084896,
    "coupon": null,
    "couponError": null,
    "createdDate": 1687528198893,
    "createdUser": "JoeSchmo",
    "depositAmount": null,
    "description": "For Advanced Dog Training with Coco moe on Friday, Jun 23, 2023 at 11:00 EDT",
    "discountAmount": null,
    "discountPercentage": null,
    "giftCardUUID": null,
    "grossAmount": 25,
    "invoiceId": null,
    "invoiceItemId": 2694646,
    "invoiceItemName": null,
    "invoiceStatus": null,
    "modifiedUser": "JoeSchmo",
    "netAmount": 25,
    "packageSoldId": null,
    "productId": null,
    "quantity": 1,
    "rate": 25,
    "reasonId": null,
    "recurringAppointmentId": null,
    "taxable": false
]

PUT /invoices

{
    "balanceAmount": 26.5,
    "billingLocationId": 282639,
    "billingStaffId": 298660,
    "businessId": 43111,
    "chargeDate": null,
    "client": {Client object for client of invoice - for more info, see Clients API page},
    "comments": null,
    "createdDate": 1687528199008,
    "createdUser": "JoeSchmo",
    "currency": "USD",
    "depositAmount": 0,
    "discountAmount": 0,
    "invoiceDate": 1687499399004,
    "invoiceDueDate": null,
    "invoiceHash": "9b0fb0fb306842328bc7af58fe0a6426",
    "invoiceId": 2523752,
    "invoiceItem": [invoiceItem object for invoice item of invoice - for more info, see Invoice Items API page],
    "invoiceNumber": 2523752,
    "invoiceTotalAmount": 26.5,
    "invoiceType": "INVOICE",
    "invoiceUrl": "https://www.timetap.com/appts/OxD8CxnD3ce",
    "lastStatus": null,
    "lastStatusDate": null,
    "location": {Location object for location of invoice - for more info, see Locations API page},
    "modifiedUser": "JoeSchmo",
    "paidAmount": 0,
    "paidOnDate": null,
    "preAuthPayment": false,
    "staff": {Staff object for staff of invoice - for more info, see Staff API page},
    "status": "OPEN",
    "subStatus": "No Payment",
    "subtotalAmount": 25,
    "tax2Amount": 0,
    "taxAmount": 0,
    "tipAmount": null,
    "transactionFeeAmount": 1.5,
    "writeOffAmount": null
}

GET /invoices/status/{statusString}

[{
    "balanceAmount": 30.07,
    "billingLocationId": 81129,
    "billingStaffId": 82275,
    "businessId": 43111,
    "chargeDate": null,
    "client": {Client object for client of invoice - for more info, see Clients API page},
    "comments": null,
    "createdDate": 1526303044509,
    "createdUser": "WebClient",
    "currency": "USD",
    "depositAmount": 0,
    "discountAmount": 1.5,
    "invoiceDate": 1526303044509,
    "invoiceDueDate": null,
    "invoiceHash": "e0ceb08f3eda4896a8f0a963b6038f5d",
    "invoiceId": 310887,
    "invoiceItem": {invoiceItem object for invoice item of invoice - for more info, see Invoice Items API page},
    "invoiceNumber": null,
    "invoiceTotalAmount": 30.07,
    "invoiceType": "INVOICE",
    "invoiceUrl": null,
    "lastStatus": null,
    "lastStatusDate": null,
    "location": {Location object for location of invoice - for more info, see Locations API page},
    "modifiedUser": "WebClient",
    "paidAmount": 0,
    "paidOnDate": null,
    "preAuthPayment": false,
    "staff": {Staff object for staff of invoice - for more info, see Staff API page},
    "status": "OPEN",
    "subStatus": "No Payment",
    "subtotalAmount": 28.5,
    "tax2Amount": 0,
    "taxAmount": 0,
    "tipAmount": null,
    "transactionFeeAmount": 1.57,
    "writeOffAmount": 0
}]

GET /invoices/{invoiceId}

{
    "balanceAmount": 10,
    "billingLocationId": 81125,
    "billingStaffId": 77961,
    "businessId": 43111,
    "chargeDate": null,
    "client": {Client object for client of invoice - for more info, see Clients API page},
    "comments": null,
    "createdDate": 1527890271428,
    "createdUser": "WebClient",
    "currency": "USD",
    "depositAmount": 0,
    "discountAmount": null,
    "invoiceDate": 1527890271428,
    "invoiceDueDate": null,
    "invoiceHash": "d76b4088e4464052876551661e80cfe7",
    "invoiceId": 319343,
    "invoiceItem": {invoiceItem object for invoice item of invoice - for more info, see Invoice Items API page},
    "invoiceNumber": null,
    "invoiceTotalAmount": 10,
    "invoiceType": "INVOICE",
    "invoiceUrl": "https://www.timetap.com/appts/OxD8Cxn8eFe",
    "lastStatus": null,
    "lastStatusDate": null,
    "location": {Location object for location of invoice - for more info, see Locations API page},
    "modifiedUser": "WebClient",
    "paidAmount": 0,
    "paidOnDate": null,
    "preAuthPayment": false,
    "staff": {Staff object for staff of invoice - for more info, see Staff API page},
    "status": "OPEN",
    "subStatus": "No Payment",
    "subtotalAmount": 10,
    "tax2Amount": 0,
    "taxAmount": 0,
    "tipAmount": null,
    "transactionFeeAmount": 0,
    "writeOffAmount": 0
}

GET /invoices/client/{clientId}

[{
    "balanceAmount": 8,
    "billingLocationId": 81181,
    "billingStaffId": 80891,
    "businessId": 43111,
    "chargeDate": null,
    "client": {Client object for client of invoice - for more info, `see clients API page},
    "comments": null,
    "createdDate": 1535477439866,
    "createdUser": "WebClient",
    "currency": "USD",
    "depositAmount": 0,
    "discountAmount": null,
    "invoiceDate": 1535477349866,
    "invoiceDueDate": null,
    "invoiceHash": "edf97b570b3f42d7a5d3d5c4d81da6b",
    "invoiceId": 433472,
    "invoiceItem": {invoiceItem object for invoice item of invoice - for more info, see Invoice Items API page},
    "invoiceNumber": null,
    "invoiceTotalAmount": 8,
    "invoiceType": "INVOICE",
    "invoiceUrl": "https://www.timetap.com/appts/Pn6sWe4o9Le",
    "lastStatus": null,
    "lastStatusDate": null,
    "location": {Location object for location of invoice - for more info, see Locations API page},
    "modifiedUser": "WebClient",
    "paidAmount": 0,
    "paidOnDate": null,
    "preAuthPayment": false,
    "staff": {Staff object for staff of invoice - for more info, see Staff API page},
    "status": "OPEN",
    "subStatus": "No Payment",
    "subtotalAmount": 8,
    "tax2Amount": 0,
    "taxAmount": 0,
    "tipAmount": null,
    "transactionFeeAmount": 0,
    "writeOffAmount": 0
}]

POST /invoices

{
    "balanceAmount": 0,
    "billingLocationId": null,
    "billingStaffId": null,
    "businessId": 43111,
    "chargeDate": null,
    "client": {Client object for client of invoice - for more info, see Clients API page},
    "comments": null,
    "createdDate": 1536075865138,
    "createdUser": "JoeSchmo",
    "currency": null,
    "depositAmount": null,
    "discountAmount": null,
    "invoiceDate": 1536075839813,
    "invoiceDueDate": null,
    "invoiceHash": "5cd7a4564eda4969858405bfa891a3a2",
    "invoiceId": 449747,
    "invoiceItem": null,
    "invoiceNumber": "2524015",
    "invoiceTotalAmount": 0,
    "invoiceType": "QUOTE",
    "invoiceUrl": null,
    "lastStatus": null,
    "lastStatusDate": null,
    "location": null,
    "modifiedUser": "JoeSchmo",
    "paidAmount": 0,
    "paidOnDate": null,
    "preAuthPayment": false,
    "status": "OPEN",
    "subStatus": null,
    "subtotalAmount": 0,
    "tax2Amount": null,
    "taxAmount": null,
    "tipAmount": 0,
    "transactionFeeAmount": null,
    "writeOffAmount": 0
}

POST /invoices/client/{clientId}

{
    "balanceAmount": 26.5,
    "billingLocationId": null,
    "billingStaffId": null,
    "businessId": 43111,
    "chargeDate": null,
    "client": {Client object for client of invoice - for more info, see Clients API page},
    "comments": null,
    "createdDate": 1687528199008,
    "createdUser": "JoeSchmo",
    "currency": "USD",
    "depositAmount": 0,
    "discountAmount": 0,
    "invoiceDate": 1687513799004,
    "invoiceDueDate": null,
    "invoiceHash": "9b0fb0fb306842328bc7af58fe0a6426",
    "invoiceId": 2523752,
    "invoiceItem": [invoiceItem object for invoice item of invoice - for more info, see Invoice Items API page],
    "invoiceNumber": null,
    "invoiceTotalAmount": 26.5,
    "invoiceType": "INVOICE",
    "invoiceUrl": null,
    "lastStatus": null,
    "lastStatusDate": null,
    "location": null,
    "modifiedUser": null,
    "paidAmount": 0,
    "paidOnDate": null,
    "preAuthPayment": false,
    "staff": null,
    "status": "OPEN",
    "subStatus": "No Payment",
    "subtotalAmount": 25,
    "tax2Amount": 0,
    "taxAmount": 0,
    "tipAmount": null,
    "transactionFeeAmount": 1.5,
    "writeOffAmount": 0
}

PUT /invoices

{
    "balanceAmount": 8,
    "billingLocationId": 87877,
    "billingStaffId": 81651,
    "businessId": 43111,
    "chargeDate": null,
    "client": {Client object for client of invoice - for more info, see Clients API page},
    "comments": null,
    "createdDate": 1526480602724,
    "createdUser": "WebClient",
    "currency": "USD",
    "depositAmount": 0,
    "discountAmount": null,
    "invoiceDate": 1526480602724,
    "invoiceDueDate": null,
    "invoiceHash": "2e4f1f2273b94867a35ee690632c87d2",
    "invoiceId": 312050,
    "invoiceItem": [invoiceItem object for invoice item of invoice - for more info, see Invoice Items API page],
    "invoiceNumber": "2523752",
    "invoiceTotalAmount": 8,
    "invoiceType": "INVOICE",
    "invoiceUrl": "https://www.timetap.com/appts/OxD8CxnD3ce",
    "lastStatus": null,
    "lastStatusDate": null,
    "location": {Location object for location of invoice - for more info, see Locations API page},
    "modifiedUser": "JoeSchmo",
    "paidAmount": 0,
    "paidOnDate": null,
    "preAuthPayment": false,
    "status": "OPEN",
    "subStatus": "No Payment",
    "subtotalAmount": 8,
    "tax2Amount": 0,
    "taxAmount": 0,
    "tipAmount": null,
    "transactionFeeAmount": 0,
    "writeOffAmount": 0
}

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.

TimeTap API

Invoices

Invoices API Endpoints

Invoices API Parameters

Invoices API Request Body/Payloads

Invoices API Responses

Invoices Object Values