REST API v1
Invoices
Manage invoices via the REST API
The Invoices API lets you create, read, update, and delete invoices in your workspace.
List Invoices
Returns a paginated list of invoices.
GET /api/v1/invoicesRequired Scope: invoices:read
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
page | integer | Page number (default: 1) |
per_page | integer | Results per page, 1-100 (default: 25) |
search | string | Search invoices by keyword |
sort_by | string | Field to sort by |
sort_direction | string | asc or desc (default: desc) |
contact_id | integer | Filter by contact ID |
job_id | integer | Filter by job ID |
exclude_children | boolean | Exclude child invoices when true |
exclude_statuses | string | Comma-separated list of statuses to exclude (e.g. draft,cancelled) |
curl https://app.bluesuite.com/api/v1/invoices?page=1&per_page=10&contact_id=42 \
-H "Authorization: Bearer wk_abc123.your_api_key"{
"success": true,
"data": [
{
"id": 1,
"name": "INV-001",
"contact_id": 42,
"status": "sent",
"total": 1500.00,
"date": "2025-03-01",
"due_date": "2025-03-31"
}
],
"pagination": {
"page": 1,
"per_page": 10,
"total_pages": 3
}
}Create Invoice
Creates a new invoice.
POST /api/v1/invoicesRequired Scope: invoices:write
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | Invoice name or number |
contact_id | integer | No | Associated contact ID |
property_id | integer | No | Associated property ID |
job_id | integer | No | Associated job ID |
quote_id | integer | No | Associated quote ID |
salesperson_id | string (UUID) | No | Assigned salesperson user ID |
date | string | No | Invoice date (YYYY-MM-DD) |
due_date | string | No | Payment due date (YYYY-MM-DD) |
send_on | string | No | Scheduled send date (YYYY-MM-DD) |
message | string | No | Message to the customer |
payment_instructions | string | No | Payment instructions text |
payment_terms | string | No | One of: due_on_receipt, net_7, net_14, net_30, net_60, net_90 (default: due_on_receipt) |
line_items | array | No | Array of line item objects (see Line Items) |
discount | number | No | Discount amount (default: 0) |
discount_unit | string | No | % or $ (default: %) |
deposit | number | No | Deposit amount (default: 0) |
deposit_unit | string | No | % or $ (default: %) |
tax_rate | number | No | Tax rate percentage (default: 0) |
tax_rate_id | integer | No | Tax rate record ID |
total | number | No | Invoice total (default: 0) |
status | string | No | One of: draft, sent, paid, overdue, cancelled, partially_paid, scheduled (default: draft) |
type | string | No | one-off or recurring (default: one-off) |
custom_fields | object | No | Custom field values |
event_ids | array of integers | No | Event IDs to associate with this invoice |
curl -X POST https://app.bluesuite.com/api/v1/invoices \
-H "Authorization: Bearer wk_abc123.your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "INV-042",
"contact_id": 42,
"job_id": 10,
"date": "2025-03-01",
"due_date": "2025-03-31",
"payment_terms": "net_30",
"line_items": [
{ "name": "Window cleaning", "quantity": 1, "unitPrice": 150 }
],
"total": 150,
"status": "draft"
}'{
"success": true,
"data": {
"id": 101,
"name": "INV-042",
"contact_id": 42,
"job_id": 10,
"status": "draft",
"total": 150,
"date": "2025-03-01",
"due_date": "2025-03-31",
"payment_terms": "net_30",
"created_at": "2025-03-01T12:00:00.000Z"
}
}Get Invoice
Returns a single invoice with expanded details (contact, job, line items, etc.).
GET /api/v1/invoices/:idRequired Scope: invoices:read
curl https://app.bluesuite.com/api/v1/invoices/101 \
-H "Authorization: Bearer wk_abc123.your_api_key"{
"success": true,
"data": {
"id": 101,
"name": "INV-042",
"contact_id": 42,
"job_id": 10,
"status": "draft",
"total": 150,
"date": "2025-03-01",
"due_date": "2025-03-31",
"payment_terms": "net_30",
"line_items": [
{ "name": "Window cleaning", "quantity": 1, "unitPrice": 150 }
],
"contact": {
"id": 42,
"first_name": "John",
"last_name": "Smith"
}
}
}Update Invoice
Updates an existing invoice. Only include the fields you want to change.
PUT /api/v1/invoices/:idRequired Scope: invoices:write
Request Body: Same fields as Create Invoice. All fields are optional.
curl -X PUT https://app.bluesuite.com/api/v1/invoices/101 \
-H "Authorization: Bearer wk_abc123.your_api_key" \
-H "Content-Type: application/json" \
-d '{
"status": "sent",
"total": 175
}'{
"success": true,
"data": {
"id": 101,
"name": "INV-042",
"status": "sent",
"total": 175
}
}Delete Invoice
Deletes an invoice.
DELETE /api/v1/invoices/:idRequired Scope: invoices:write
curl -X DELETE https://app.bluesuite.com/api/v1/invoices/101 \
-H "Authorization: Bearer wk_abc123.your_api_key"{
"success": true,
"data": {
"deleted": true
}
}Update Invoice Status
Updates only the status of an invoice.
PUT /api/v1/invoices/:id/statusRequired Scope: invoices:write
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
status | string | Yes | One of: draft, sent, paid, overdue, cancelled, partially_paid, scheduled |
curl -X PUT https://app.bluesuite.com/api/v1/invoices/101/status \
-H "Authorization: Bearer wk_abc123.your_api_key" \
-H "Content-Type: application/json" \
-d '{ "status": "paid" }'{
"success": true,
"data": {
"id": 101,
"status": "paid"
}
}Line Items
Line items represent individual services or products on an invoice. When creating or updating an invoice, provide line items in this format:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Item name |
description | string | No | Additional description |
quantity | number | No | Quantity (default: 1) |
unitPrice | number | Yes | Unit price |
taxable | boolean | No | Whether the item is taxable |
optional | boolean | No | Whether the item is optional |
The API automatically assigns each line item a unique id and _type field. Response objects will include these generated fields.
{
"line_items": [
{ "name": "Window cleaning", "quantity": 1, "unitPrice": 150 },
{ "name": "Gutter cleaning", "quantity": 1, "unitPrice": 75, "description": "Front and back" }
]
}