Invoice

• Allowed query parameters
• Create an invoice
• Update an invoice
• Retrieve an invoice
• Delete an invoice
• List invoices
• Invoice line items
• Add products to an invoice
• Update invoice status
• Send an invoice
• Invoice payments

Allowed query parameters

Filters

Filter	Type	Description
search	String	Full-text search
own	Boolean	Show only own invoices
project	Id	Filter by Project Id
company	String	Filter by Company Id
contact	String	Filter by Contact Id
product	String	Filter by Product Id
status	String	Filter based on status: paid, pending, overdue, draft, dunned, paidOrPending
date_range	DateRange	Filter by issued date <start-date>,<end-date>
total_range	NumberRange	Filter by total amount <min-amount>,<max-amount> or just <min-amount>
net_total_range	NumberRange	Filter by net total amount <min-amount>,<max-amount> or just <min-amount>
member	String	Filter by Member Id
recurring	Boolean	Show only recurring invoices
exported	Boolean	Show only exported invoices
custom_field	Key,String	Filter by Custom Field (eg. my_internal_id,42)
trashed	Boolean	Include soft-deleted invoices

Sorting

issued_at, due_at, paid_at, number_sequence, created_at

Includes

project.invoices, project.unbilledExpenses, contact.company.media, company.media, elements.tag, elements.product, member.user.media, createdBy.user.media, updatedBy.user.media, activities, expenses, expensesCount, lockedTimes, lockedTimesCount, sourceOffer, bankAccount, comments.commentator.media, payments.bankAccount, media

Create an invoice

post

/invoice

Attribute (* required)	Type	Description
name	String?	Invoice title (max 255 characters)
project_id	String?	A Project Id (min 10 characters)
contact_id *	String	A Contact Id (min 10 characters)
include_vat	Boolean	With/without taxes
issued_at	Date	Issue date
due_at	Date?	Due date (must be after or equal to issued_at)
due_within	Number?	Due in days (0-365, used when due_at is empty)
paid_at	Date?	Paid date (must be after issued_at)
description	String?	Invoice description
reminded	Number	Dunning level (0 to max dunning levels)
address	String?	Recipient Address
header	String?	Header text
footer	String?	Footer text
has_page_break_after_header	Boolean	Add page break after header
has_page_break_before_footer	Boolean	Add page break before footer
recurring_type	String?	Recurrence type (weeks, months, years)
recurring_every	Number?	Recurrence interval (1-99)
recurring_ends_at	Date?	Recurrence end date
revenue_account_no	String?	Revenue account number
bank_account_id	String?	Bank account ID (min 10 characters)
custom_fields	Object?	Custom data as Custom Fields

Example response

// HTTP 201 Created
{
    // an invoice object
}

Update an invoice

put

/invoice/{id}

Attribute (* required)	Type	Description
name	String?	Invoice title (max 255 characters)
project_id	String?	A Project Id (min 10 characters)
contact_id	String	A Contact Id (min 10 characters)
total	Number?	Total amount (max 999999)
include_vat	Boolean	With/without taxes
is_scheduled_for_sending	Boolean	Schedule invoice for auto-sending
issued_at	Date	Issue date (must be before or equal to due_at)
due_at	Date	Due date (must be after or equal to issued_at)
paid_at	Date?	Paid date (must be after issued_at)
sent_at	Date?	Sent date
description	String?	Invoice description
reminded	Number	Dunning level (0 to max dunning levels)
address	String	Recipient Address
header	String?	Header text
footer	String?	Footer text
has_page_break_after_header	Boolean	Add page break after header
has_page_break_before_footer	Boolean	Add page break before footer
recurring_type	String?	Recurrence type (weeks, months, years)
recurring_every	Number?	Recurrence interval (1-99)
recurring_ends_at	Date?	Recurrence end date
revenue_account_no	String?	Revenue account number
is_exported	Boolean	Whether invoice has been exported
bank_account_id	String?	Bank account ID (min 10 characters)
custom_fields	Object?	Custom data as Custom Fields

Example response

// HTTP 200 OK
{
    // an invoice object
}

Retrieve an invoice

get

/invoice/{id}

Example response

// HTTP 200 OK
{
    "id": "D4rNdYjlGy",
    "number": "RE-01234",
    "name": "Jahresretainer 2023",
    "description": null,
    "reminded": 0,
    "current_dunning_level": null,
    "next_dunning_level": null,
    "dunning_text": null,
    "total": 7680.0,
    "total_with_vat": 8271.35,
    "external_total": 0.0,
    "total_paid": 0.0,
    "total_open": 8271.35,
    "include_vat": true,
    "vat_detailed": {
        "7.7": {
            "rate": 7.7,
            "net": 7680.0,
            "tax": 591.35
        }
    },
    "is_paid": false,
    "is_sent": false,
    "is_scheduled_for_sending": false,
    "is_rfd": false,
    "is_locked": true,
    "is_exported": false,
    "is_overdue": false,
    "is_overpaid": false,
    "issued_at": "2022-09-19",
    "due_at": "2022-10-19",
    "sent_at": null,
    "locked_at": "2022-09-19T13:51:35.000000Z",
    "paid_at": null,
    "days_overdue": 0,
    "payable_in_days": 30,
    "address": "<p><strong>StrawBlond</strong><br> Alice Cooper<br>Rütistrasse 2<br>CH-8645 Rapperswil</p>",
    "header": "<p>Sehr geehrte Damen und Herren</p><p>Vielen Dank für Ihren Auftrag. Wir stellen Ihnen folgende Leistungen/Lieferungen in Rechnung:</p>",
    "footer": "<p>Vielen Dank für eine fristgerechte Zahlung.</p><p>Freundliche Grüsse<br>StrawBlond GmbH</p>",
    "address_personalized": "<p><strong>StrawBlond</strong><br> Alice Cooper<br>Rütistrasse 2<br>CH-8645 Rapperswil</p>",
    "header_personalized": "<p>Sehr geehrte Damen und Herren</p><p>Vielen Dank für Ihren Auftrag. Wir stellen Ihnen folgende Leistungen/Lieferungen in Rechnung:</p>",
    "footer_personalized": "<p>Vielen Dank für eine fristgerechte Zahlung.</p><p>Freundliche Grüsse<br>StrawBlond GmbH</p>",
    "has_page_break_after_header": false,
    "has_page_break_before_footer": false,
    "show_qrbill": true,
    "pdf_url": "https://api.strawblond.com/api/invoice/1502/pdf?expires=1666195512&signature=af336a31dc989b7755b4a1391e7134226d5697e926711080130aaa12b2689470",
    "pdf_dunning_url": "https://api.strawblond.com/api/invoice/1502/pdf?expires=1666195512&options%5BwithDunningText%5D=1&signature=f476ce81ccc72230e5efdb9e7cc09af83f4b7fdf266dfd176fbd72e066400d14",
    "preview_url": "https://api.strawblond.com/api/invoice/1502/view?signature=89c4deac39578b4a961a15eddb7a2c648edeb60ccd30a091c13cc8cd48435d30",
    "mail_preview_url": "https://api.strawblond.com/api/document/mail-preview?type=invoice&id=D4rNdYjlGy",
    "project": {
        // Project object when included
    },
    "contact": {
        // Contact object when included
    },
    "member": {
        // Member object when included
    },
    "created_by": {
        // Member object when included
    },
    "updated_by": {
        // Member object when included
    },
    "company": {
        // Company object when included
    },
    "elements": [
        // Only present when included `elements` relation
        {
            // a document element object
        }
    ],
    "activities": [
        // Only present when included `activities` relation
    ],
    "expenses": [
        // Only present when included `expenses` relation
    ],
    "locked_times": [
        // Only present when included `lockedTimes` relation
    ],
    "locked_times_count": 0,
    "attachments_download_url": null,
    "source_offer": {
        // Offer object when included
    },
    "revenue_account_no": "3000",
    "is_recurring": false,
    "recurring_invoice": {
        // Invoice object when included
    },
    "recurring_type": null,
    "recurring_every": 1,
    "recurring_ends_at": null,
    "next_recurring_issue_date": null,
    "next_recurring_due_date": null,
    "bank_account_id": "AbCdEfGhIj",
    "bank_account": {
        // BankAccount object when included
    },
    "comments": [
        // Only present when included `comments` relation
    ],
    "payments": [
        // Only present when included `payments` relation
    ],
    "payment_status": "unpaid",
    "attachments": [
        // Only present when included `media` relation
    ],
    "custom_fields": {},
    "created_at": "2022-09-19T13:50:07.000000Z",
    "updated_at": "2022-09-19T13:51:35.000000Z",
    "deleted_at": null
}

Delete an invoice

delete

/invoice/{id}

Example response

// HTTP 204 No Content

List invoices

get

/invoice

The list endpoint accepts the same parameters as in Retrieve an invoice and returns a paginated array of the same invoice object in the data property.

Read more about Pagination, Filtering, Sorting and Includes on the Introduction page.

Invoice line items

You may use the Document Element endpoint to create, update or delete line items on an invoice.

Add products to an invoice

post

/invoice/{id}/add-products

Attribute (* required)	Type	Description
products *	Array	Array of Product IDs to add to the invoice
beforeOrder	Number?	Order position to insert products before (if not provided, adds to the end)

Example request

{
    "products": ["6k2KpJY3By", "8m3LqKZ4Cx"],
    "beforeOrder": 2
}

Example response

// HTTP 200 OK
{
    // an invoice object
}

Update invoice status

post

/invoice/{id}/status

Updates the status of an invoice, handling appropriate transitions and side effects like payments, notifications, and activity logging.

Attribute (* required)	Type	Description
status *	String	Invoice status: draft, pending, or paid
paid_at	Date?	Payment date (required when status is paid)
notify_customer	Boolean	Send notification to customer when marking as paid (default: false)

Status transitions

• draft: Removes all payments, unlocks invoice, clears sent/paid dates
• pending: Locks invoice, marks as sent, removes latest payment if exists
• paid: Creates payment record for remaining balance, sets paid date

Example request

{
    "status": "paid",
    "paid_at": "2023-10-15",
    "notify_customer": true
}

Example response

// HTTP 200 OK
{
    // an invoice object
}

Send an invoice

post

/invoice/{id}/send

Attribute (* required)	Type	Description
recipients	String	List of emails (separated by ";", Default: Contact email)
increaseDunningLevel	Boolean	Auto increase dunning level on overdue invoice
message	String?	Custom message to include with the invoice
ccToOwner	Boolean	Send a carbon copy to self
adjustDates	Boolean	Adjust dates to today on draft invoice
attachments	Array	Array of media UUIDs to attach to the invoice

Example response

// HTTP 200 OK
{
    // an invoice object
}

Invoice payments

You can manage incoming customer payments for invoices using the Invoice Payment endpoints. These payments automatically handle overpayments, update invoice payment status, and integrate with customer account management for comprehensive payment tracking.