ARPilot API (1.6.0)

Create an invoice manually or from line items. Either amount (legacy single-line) or line_items[] (with optional tax_amount / discount_amount) must produce a positive total. If both are provided, line-items math must match amount within $0.01.

invoice_number is optional — if omitted, the server generates one in the format {prefix}-{YYYY}-{NNNN} (prefix defaults to INV, configurable per tenant; sequence resets each calendar year).

After creation, the invoice status is automatically recalculated from its financial fields (amount, amount_due, external_payment_amount). For example, if amount_due is 0, status will be auto-corrected to 'paid' regardless of the status provided. Terminal statuses ('cancelled', 'draft') are respected and not auto-corrected.

source_type is set to api on every invoice created through this endpoint so the platform can distinguish API-originated invoices from QuickBooks imports for future two-way sync.

When financial fields (amount, amount_due, external_payment_amount, status) are modified, the invoice balance and status are automatically recalculated. Cross-field validation ensures amount_due cannot exceed amount and external_payment_amount cannot exceed amount. Terminal statuses ('cancelled', 'draft') bypass auto-recalculation and are applied directly.

Four actions selectable via ?action=:

• upload_pdf — attach a caller-supplied base64-encoded PDF (sets pdf_source: 'user_upload').
• delete_pdf — remove the current PDF and clear pdf_source.
• generate_pdf — render a branded PDF on the server using the tenant's user_branding (sets pdf_source: 'arpilot_generated'). Returns 409 if the invoice already has a user_upload or quickbooks PDF — delete it first. Regenerating over an existing arpilot_generated PDF is idempotent.
• send — send the invoice to its customer using a chosen email template, immediately or scheduled. Requires template_id (an email template with template_stage='initial_send' — discover via GET /v1/templates). Optional scheduled_date (ISO-8601; omit for send-now). Optional cc_self. Flips invoice status draft → pending idempotently. No source_type restriction — works on QuickBooks-imported invoices too.

Uploading replaces any existing PDF.

Returns a paginated list of email templates eligible to use with POST /v1/invoices/{id}?action=send. Filters: type='email' AND template_stage='initial_send'. Dunning / collections templates are excluded — they're not valid first-touch sends. Includes templates owned by the key holder (user_id matches) plus system templates (user_id IS NULL). Read-only by design — template authoring lives in the ARPilot UI. Reuses the invoices API key scope; no separate scope to rotate.

Update customer fields, tags, and/or contacts. Contacts use upsert semantics: include 'id' to update an existing contact, omit 'id' to create a new one. Contacts not mentioned in the array are left untouched. When contact email, name, or phone changes, pending scheduled communications are automatically refreshed.

Returns paginated contacts for a given customer, ordered by escalation_level.

Create a new contact for a customer. Requires customer_id, contact_name, and email. When created, if email/phone triggers downstream changes, scheduled communications are updated automatically.

Update contact fields. Only include fields you want to change. Changes to email, name, or phone automatically refresh pending scheduled communications.

Delete a contact. Cannot delete the last contact for a customer. If the deleted contact was primary, the next contact by escalation_level is auto-promoted.

Register a new HTTPS endpoint to receive events. The signing secret is returned only in this response and cannot be retrieved again.

Permanently deletes the endpoint and all delivery history.

Queues a webhook.test event to this endpoint so you can verify your server receives and validates signatures correctly.