Invoices

The Invoice object represents an invoice record in your Custom Trades CRM account.

View as Markdown

Endpoints

GET/api/v1/invoices

GET/api/v1/invoices/{uuid}

POST/api/v1/invoices

POST/api/v1/invoices/preview

PUT/api/v1/invoices/{uuid}

DELETE/api/v1/invoices/{uuid}

The Invoice object

Attributes

uuidstring

Unique identifier for the invoice

invoice_numberstring |null

Invoice number (assigned automatically; cannot be set when creating. Use [Numbering](/developer/docs/rest/api/numbering) to view or change the next number.)

customer_uuidUUID

Customer UUID (required)

job_uuidUUID |null

Associated job UUID

estimate_uuidUUID |null

Associated estimate UUID

location_uuidUUID |null

Location UUID

invoice_typestring

Type: 'Full', 'Partial', 'Progress'

progress_percentagenumber |null

Progress percentage (for progress invoices)

issue_datestring

Issue date (YYYY-MM-DD format)

due_datestring

Due date (YYYY-MM-DD format)

subtotalnumber

Subtotal amount

tax_amountnumber

Tax amount

discount_amountnumber

Discount amount

total_amountnumber

Total amount

paid_amountnumber

Paid amount

balance_amountnumber

Balance amount

line_itemsJSONB |null

Line items array

notesstring |null

Customer-facing notes

termsstring |null

Payment terms

internal_notesstring |null

Internal notes

statusstring

Status: 'Draft', 'Pending', 'Paid', 'Overdue'

created_atstring

ISO timestamp of creation

updated_atstring

ISO timestamp of last update

deleted_atstring |null

ISO timestamp of soft deletion (null if not deleted)

View as Markdown

THE INVOICE OBJECT

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "invoice_number": "INV-001",
  "status": "Pending",
  "total_amount": 500,
  "balance_amount": 500,
  "due_date": "2025-02-01",
  "customer": {
    "uuid": "...",
    "first_name": "John",
    "last_name": "Doe"
  }
}

List invoices

Returns a paginated list of invoices for your company.

Parameters

include_deleted(boolean, default: false)required

Include soft-deleted invoices

status(string)

Filter by status ('All', 'Pending', 'Paid', 'Overdue', 'Draft')

customer_uuid(UUID)

Filter by customer

job_uuid(UUID)

Filter by job

search(string)

Search term (searches invoice_number)

page(number, default: 1)required

Page number

limit(number, default: 50, max: 100)required

Items per page

GET/api/v1/invoices

curl -G \
  https://customtradescrm.com/api/v1/invoices?status=Pending \
  -H "Authorization: Bearer ctc_live_..."

Response

{
  "success": true,
  "data": {
    "invoices": [
      {
        "uuid": "123e4567-e89b-12d3-a456-426614174000",
        "invoice_number": "INV-001",
        "status": "Pending",
        "total_amount": 500,
        "balance_amount": 500,
        "due_date": "2025-02-01",
        "customer": {
          "uuid": "...",
          "first_name": "John",
          "last_name": "Doe"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "total_pages": 1
    }
  }
}

Get an invoice

Returns a specific invoice by UUID with related customer, job, estimate, and location information.

GET/api/v1/invoices/{uuid}

curl -G \
  https://customtradescrm.com/api/v1/invoices/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer ctc_live_..."

Create an invoice

Creates a new invoice from a completed job. **Request Body:** You can send **multiple line items** in `line_items` (labor, parts, fees). Each item uses `description`, `quantity`, `unit_price`, and optional `tax_rate`. Example with labor, parts, and a fee:

Parameters

job_uuid(string)required

Job UUID (must belong to your company)

customer_uuid(string)required

Customer UUID (must belong to your company)

due_date(string)required

Due date (YYYY-MM-DD format)

estimate_uuid(string)

Associated estimate UUID

location_uuid(string)

Location UUID

invoice_type(string)

'Full', 'Partial', or 'Progress' (default: 'Full')

progress_percentage(string)

Progress percentage (for progress invoices)

issue_date(string)

Issue date (YYYY-MM-DD format, default: today)

line_items(string)

**Array of line items** (see [Line items](#line-items) above). Each item: `description` (optional), `quantity` (optional, default 1), `unit_price` (required), `tax_rate` (optional). You can include as many items as needed (e.g. labor, parts, fees).

subtotal(string)

Subtotal (calculated from line_items if not provided)

tax_amount(string)

Tax amount (calculated from line_items if not provided)

discount_amount(string)

Discount amount (default: 0)

notes(string)

Customer-facing notes

terms(string)

Payment terms

internal_notes(string)

Internal notes

POST/api/v1/invoices

curl -G \

Response

{
  "job_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "customer_uuid": "123e4567-e89b-12d3-a456-426614174001",
  "due_date": "2025-02-01",
  "invoice_type": "Full",
  "line_items": [
    {
      "description": "Labor",
      "quantity": 8,
      "unit_price": 95,
      "tax_rate": 0
    },
    {
      "description": "Replacement parts",
      "quantity": 2,
      "unit_price": 50,
      "tax_rate": 8.5
    },
    {
      "description": "Trip fee",
      "quantity": 1,
      "unit_price": 75,
      "tax_rate": 0
    }
  ],
  "notes": "Payment due within 30 days"
}

Preview invoice totals (dry run)

Preview invoice totals without creating the invoice. This is useful for calculating totals including tax before creating the invoice. **Request Body:** Send the same `line_items` shape as for create (multiple items allowed). Example with labor, parts, and discount:

Parameters

job_uuid(string)

Job UUID (used to get job amounts if `line_items` not provided)

line_items(string)

Array of line items (see [Line items](#line-items)); multiple items supported

subtotal(string)

Subtotal (used if `line_items` not provided)

tax_amount(string)

Tax amount (overrides calculated tax)

discount_amount(string)

Discount amount (default: 0)

POST/api/v1/invoices/preview

curl -G \

Response

{
  "success": true,
  "data": {
    "preview": {
      "subtotal": 860,
      "tax_amount": 8.5,
      "discount_amount": 25,
      "total_amount": 843.5,
      "balance_amount": 843.5
    },
    "breakdown": {
      "line_items": [
        {
          "description": "Labor",
          "quantity": 8,
          "unit_price": 95,
          "line_total": 760,
          "tax_rate": 0,
          "tax_amount": 0
        },
        {
          "description": "Parts",
          "quantity": 2,
          "unit_price": 50,
          "line_total": 100,
          "tax_rate": 8.5,
          "tax_amount": 8.5
        }
      ]
    }
  }
}

Update an invoice

Updates an invoice. All fields are optional (partial update). **Request Body:**

PUT/api/v1/invoices/{uuid}

curl -G \

Response

{
  "status": "Paid",
  "notes": "Payment received"
}

Delete an invoice

Soft deletes an invoice (sets `deleted_at` timestamp).

Error codes

HTTP status code	Description
200	Success
400	Validation error
401	Unauthorized (invalid API key)
403	Forbidden (add-on required, IP restriction, or usage limit exceeded)
404	Invoice not found
500	Server error

DELETE/api/v1/invoices/{uuid}

curl -X DELETE \
  https://customtradescrm.com/api/v1/invoices/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer ctc_live_..."