Skip to Content
Invoice Management API

Invoice Management API

The Invoice Management API allows you to manage invoices in your TaskIP system. You can create, read, update, and delete invoices, as well as perform advanced operations like status updates, publishing, payment gateway selection, recurring billing, PDF download, and sending invoices to clients.

Endpoints Overview

MethodEndpointDescription
GET/api/public-v1/invoiceGet all invoices
POST/api/public-v1/invoiceCreate a new invoice
GET/api/public-v1/invoice/{id}Get a specific invoice
PUT / PATCH/api/public-v1/invoice/{id}Update an invoice
DELETE/api/public-v1/invoice/{id}Delete an invoice
POST/api/public-v1/invoice/bulk-actionsBulk operations on invoices
POST/api/public-v1/invoice/{id}/status-updateUpdate invoice status
POST/api/public-v1/invoice/publish/{id}Publish/unpublish invoice
POST/api/public-v1/invoice/{id}/payment-gatewayUpdate payment gateway
POST/api/public-v1/invoice/{id}/recurringSet up recurring payments
GET/api/public-v1/invoice/{id}/downloadDownload invoice PDF
POST/api/public-v1/invoice/sent/{id}Send invoice to client (rate limited)
💡

For get, update, delete, status-update and send, {id} may be the numeric invoice ID or the invoice number (invoice_no). The publish endpoint also accepts either the numeric ID or the invoice number; the payment-gateway, recurring and download endpoints require the numeric ID.

Value Reference

Invoice status

ValueMeaning
0Draft
1Sent
2Pending
3Overdue
4Paid
5Partially Paid
6Void
7Refunded
8Canceled
9Accepted
10Failed

Money amounts: amounts are stored in the smallest currency unit (cents). Responses return subtotal, total, partial_paid_amount and due_amount already divided by 100. On create, subtotal and total are stored as sent (cents); on update they are recalculated by the server (see Update an Invoice).


Get All Invoices

Retrieve a paginated list of invoices, newest first.

GET /api/public-v1/invoice

Request Headers

X-Secret-Key: your-secret-key-here Content-Type: application/json

Query Parameters

ParameterTypeRequiredDescription
pageintegerNoPage number for pagination
itemintegerNoInvoices per page (default: 10). 0 returns all invoices without pagination
searchstringNoMatches the invoice number (invoice_no), subject, the contact’s name/email, or the contact company’s email. If the term exactly equals an invoice’s generatedId, only that invoice is returned
statusintegerNoFilter by status (0-10, see Value Reference)
fromstringNoStart date (YYYY-MM-DD). Must be used together with to
tostringNoEnd date (YYYY-MM-DD)

Example Request

curl -X GET "https://public-api.taskip.net/api/public-v1/invoice?page=1&item=20&status=1&search=website" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json"

JavaScript Example

const response = await fetch('https://public-api.taskip.net/api/public-v1/invoice?page=1&item=20', { method: 'GET', headers: { 'X-Secret-Key': 'your-secret-key-here', 'Content-Type': 'application/json' } }); const invoices = await response.json();

Example Response

{ "message": "Invoice list", "data": [ { "id": 157, "invoice_no": "INV-2024-157", "generatedId": "INV-2024-157", "slug": null, "folder": null, "company_id": null, "company": { "id": 15, "name": "Acme Corporation", "email": "billing@acme.com" }, "contacts": { "id": 45, "first_name": "John", "last_name": "Smith", "email": "john@acme.com" }, "contact_id": 45, "lead_id": null, "lead": null, "subject": "Q1 Marketing Services", "issue_date": "2024-01-25", "due_date": "2024-02-25", "currency": "usd", "subtotal": 3000.00, "currentNote": { "id": "INV-2024-157", "note": "Payment Terms", "term": "Payment due within 30 days" }, "notes": [ { "id": 1, "note_id": 31, "title": "Payment Terms", "description": "Payment due within 30 days", "enable": 1, "order_number": 1, "created_at": "2024-01-25T10:30:00.000000Z", "updated_at": "2024-01-25T10:30:00.000000Z" } ], "total": 3300.00, "partial_paid_amount": 0, "due_amount": 3300, "items": [ { "name": "Website Development", "qty": 1, "rate": 2500, "label": "Service" } ], "logo": null, "signature": null, "discount": 0, "discount_type": "percent", "template": 1, "payment_gateway": "stripe_payment", "payment_infos": [], "status": 1, "publish": false, "deleted_at": null, "activities": [], "reminders": { "reminder_status": 0, "reminder_moment": "", "reminder_duration": "", "reminder_time": "", "reminder_message": "", "reminder_note": "" }, "payable": { "payable_amount": 3300, "payable_amount_type": "fixed_amount", "payment_type": "full-amount" }, "recurring_payment": { "is_payment_reccuring": false, "payment_recurring_type": null, "recurring_until": "1970-01-01" }, "recurring_payment_id": null, "created_by": { "first_name": "Admin", "last_name": "User", "full_name": "Admin User", "name": "Admin", "email": "admin@taskip.com", "image": null }, "updated_by": { "first_name": "Admin", "last_name": "User", "full_name": "Admin User", "name": "Admin", "email": "admin@taskip.com", "image": null }, "updated_at": "2024-01-25T10:30:00.000000Z", "created_at": "2024-01-25T10:30:00.000000Z", "multiple_payment_gateway": null } ], "links": { "first": "https://public-api.taskip.net/api/public-v1/invoice?page=1", "last": "https://public-api.taskip.net/api/public-v1/invoice?page=3", "prev": null, "next": "https://public-api.taskip.net/api/public-v1/invoice?page=2" }, "meta": { "current_page": 1, "from": 1, "last_page": 3, "path": "https://public-api.taskip.net/api/public-v1/invoice", "per_page": 10, "to": 10, "total": 25 } }

Notes on the response object:

  • invoice_no is set when the invoice is created and never changes afterwards. generatedId is the formatted display number, also frozen at creation, so later changes to your numbering settings do not renumber existing invoices.
  • status is the numeric code from the Value Reference.
  • recurring_until shows 1970-01-01 when no recurring end date is set.
  • meta.search is only present when search was used.
  • The selected tax details (taxes, total_tax, global_tax_id, tax_rate) and theme are not included in public API responses. Taxes are applied when you update an invoice, and they are reflected in total.

Create an Invoice

Create a new invoice. Provide at most one billing party (contact_id, lead_id or company_id); if any of them is sent, exactly one must have a value.

POST /api/public-v1/invoice

Request Headers

X-Secret-Key: your-secret-key-here Content-Type: application/json

Request Body

FieldTypeRequiredDescription
invoice_nostringYesInvoice number; must be unique. A purely numeric value is replaced by a random 10-character uppercase code. The number is frozen once created
subjectstringYesInvoice subject (max 191 characters)
currencystringYesCurrency code (max 191 characters; stored lower-case)
contact_idintegerNoContact ID to bill (must exist)
lead_idintegerNoLead ID to bill (must exist)
company_idintegerNoCompany ID to bill (must exist)
project_idstringNoFolder ID to file the invoice in
issue_datestringNoIssue date (YYYY-MM-DD)
due_datestringNoDue date (YYYY-MM-DD)
subtotalnumberNoSubtotal in the smallest currency unit (cents)
discountnumberNoDiscount value
discount_typestringNoDiscount type (default: percent)
totalnumberNoTotal in the smallest currency unit (cents)
itemsstringNoLine items as a JSON-encoded string (see below)
logointegerNoLogo media ID
signatureintegerNoSignature media ID
termsstringNoInvoice terms
statusintegerNoOnly 0 (Draft) or 1 (Sent) are accepted. Defaults to 0
⚠️

The create endpoint does not calculate totals, taxes or notes. It stores subtotal, total and items exactly as you send them. To select taxes (one or many), add notes, recurring settings or payable settings, or have totals recalculated by the server, follow up with Update an Invoice.

Invoice Item Object (inside the items JSON string)

FieldTypeRequiredDescription
namestringYesItem name/description
qtynumberYesItem quantity
ratenumberYesPrice per unit
labelstringNoItem unit label

Example Request

curl -X POST "https://public-api.taskip.net/api/public-v1/invoice" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json" \ -d '{ "invoice_no": "INV-2024-001", "contact_id": 1, "subject": "Website Development Services", "issue_date": "2024-01-25", "due_date": "2024-02-25", "currency": "USD", "subtotal": 300000, "discount": 0, "discount_type": "percent", "total": 300000, "items": "[{\"name\":\"Website Development\",\"qty\":1,\"rate\":2500,\"label\":\"Service\"},{\"name\":\"SEO Optimization\",\"qty\":1,\"rate\":500,\"label\":\"Service\"}]", "status": 0 }'

Python Example

import json import requests headers = { 'X-Secret-Key': 'your-secret-key-here', 'Content-Type': 'application/json' } invoice_data = { "invoice_no": "INV-2024-001", "contact_id": 1, "subject": "Website Development Services", "issue_date": "2024-01-25", "due_date": "2024-02-25", "currency": "USD", "subtotal": 300000, "total": 300000, "items": json.dumps([ {"name": "Website Development", "qty": 1, "rate": 2500, "label": "Service"}, {"name": "SEO Optimization", "qty": 1, "rate": 500, "label": "Service"} ]) } response = requests.post( 'https://public-api.taskip.net/api/public-v1/invoice', headers=headers, json=invoice_data ) result = response.json()

Example Response

Status: 200 OK

{ "msg": "Invoice Created", "status": 200, "invoice_no": "INV-2024-158", "invoice": { "id": 158, "invoice_no": "INV-2024-001", "generatedId": "INV-2024-158", "subject": "Website Development Services", "currency": "usd", "subtotal": 3000.00, "total": 3000.00, "partial_paid_amount": 0, "due_amount": 3000, "status": 0, "publish": false } }

The top-level invoice_no is the formatted generatedId, not the invoice_no you sent. The invoice object has the same shape as in Get All Invoices, plus currentTax and schedule (abbreviated above). Validation failures return 422 with { "error": { "<field>": ["..."] } }.


Get a Specific Invoice

GET /api/public-v1/invoice/{id}

Path Parameters

ParameterTypeRequiredDescription
idinteger or stringYesInvoice ID or invoice number

Example Request

curl -X GET "https://public-api.taskip.net/api/public-v1/invoice/157" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json"

Example Response

The response is the invoice object itself (not wrapped in data), with the same fields as an item in Get All Invoices:

{ "id": 157, "invoice_no": "INV-2024-157", "generatedId": "INV-2024-157", "slug": null, "folder": null, "company_id": null, "company": null, "contacts": { "id": 45, "first_name": "John", "last_name": "Smith", "email": "john@acme.com" }, "contact_id": 45, "lead_id": null, "lead": null, "subject": "Q1 Marketing Services", "issue_date": "2024-01-25", "due_date": "2024-02-25", "currency": "usd", "subtotal": 3000.00, "currentNote": { "id": "INV-2024-157", "note": null, "term": null }, "notes": [ { "id": 1, "title": "Default Note", "description": "Default description", "enable": true } ], "total": 3300.00, "partial_paid_amount": 1000.00, "due_amount": 2300.00, "items": [ { "name": "Website Development", "qty": 1, "rate": 2500, "label": "Service" } ], "logo": null, "signature": null, "discount": 0, "discount_type": "percent", "template": 1, "payment_gateway": "stripe_payment", "payment_infos": [], "status": 5, "publish": false, "deleted_at": null, "activities": [], "reminders": {}, "payable": { "payable_amount": 3300, "payable_amount_type": "fixed_amount", "payment_type": "full-amount" }, "recurring_payment": { "is_payment_reccuring": false, "payment_recurring_type": null, "recurring_until": "1970-01-01" }, "recurring_payment_id": null, "created_by": { "full_name": "Admin User", "email": "admin@taskip.com" }, "updated_by": { "full_name": "Admin User", "email": "admin@taskip.com" }, "updated_at": "2024-01-25T10:30:00.000000Z", "created_at": "2024-01-25T10:30:00.000000Z", "multiple_payment_gateway": null }

A missing invoice returns 404 with { "status": 404, "msg": "Invoice not found" }.


Update an Invoice

Update an existing invoice. Supports both PUT and PATCH. All data is wrapped in a top-level invoice object.

PUT /api/public-v1/invoice/{id} PATCH /api/public-v1/invoice/{id}

Path Parameters

ParameterTypeRequiredDescription
idinteger or stringYesInvoice ID or invoice number

Request Body

Send a JSON object with a single invoice key. The fields below go inside it.

FieldTypeRequiredDescription
invoice.idintegerYesInvoice ID (must exist)
invoice.invoice_nostringNoAccepted but ignored: the invoice number is frozen at creation
invoice.contactsintegerNoContact ID to bill (must exist)
invoice.lead_idintegerNoLead ID to bill (must exist)
invoice.company_idintegerNoCompany ID to bill (must exist)
invoice.payment_gatewaystringNoStored as given, e.g. stripe_payment. Omitting it clears the stored gateway; prefer the Update Payment Gateway endpoint
invoice.templateintegerNoTemplate ID (default: 1)
invoice.subjectstringNoInvoice subject
invoice.issue_datestringNoIssue date (YYYY-MM-DD)
invoice.due_datestringNoDue date (YYYY-MM-DD)
invoice.currencystringNoCurrency code
invoice.itemsarrayNoLine items (see below)
invoice.subtotalnumberNoAccepted but ignored: the server recalculates the subtotal from the items
invoice.totalnumberNoAccepted but ignored: the server recalculates the total
invoice.discountnumberNoDiscount value
invoice.discount_typestringNopercent or amount (default: percent)
invoice.taxarray of integerNoIDs of the global taxes to apply. Multiple taxes can be selected; their rates are added together
invoice.global_tax_idintegerNoLegacy single global tax ID; used only when tax is empty
invoice.tax_ratenumberNoManual tax rate (0-100); used only when neither tax nor global_tax_id resolves a tax
invoice.notesarrayNoNotes (see below). Notes missing from the array are deleted
invoice.recurring_paymentobjectNoRecurring settings (see below)
invoice.payableobjectNoPayable settings (see below)
invoice.themestringNoAccepted (max 191) but not stored
invoice.logointegerNoLogo media ID
invoice.signatureintegerNoSignature media ID
invoice.multiple_payment_gatewayarrayNoAccepted; not stored by the update

If any of contacts, lead_id or company_id is present in the request, exactly one of them must have a value (error on invoice.contacts otherwise). Billing fields you leave out are cleared.

invoice.items[]

FieldTypeRequiredDescription
idintegerNoItem ID
namestringNoItem name
qtynumberNoQuantity
ratenumberNoUnit price
labelstringNoItem label
taxnumberNoLegacy per-item tax percentage (max 100); used only when the invoice has no tax selection
taxesarray of integerNoGlobal tax IDs that replace the invoice-level taxes for this line only
service_uuidstringNoUUID of a service from your service catalog to link to this line (must exist)
package_idintegerNoID of a service package to link to this line (must exist)

invoice.notes[]: id (integer, optional), title (string), description (string), enable (boolean). Entries without a description are skipped.

Notes are synced with the payload: an entry whose id belongs to this invoice is updated in place, an entry without an id (or with an id that does not belong to this invoice) is created as a new note, and existing notes that are missing from the payload are deleted. Sending the same notes back with their id therefore does not duplicate them.

invoice.recurring_payment

FieldTypeDescription
is_payment_reccuringbooleanEnable recurring billing (note the spelling)
payment_recurring_typestringRecurrence type (max 50)
start_fromdateStart date
recurring_untilstringEnd date

The recurring values are only saved when is_payment_reccuring is true; otherwise they are cleared.

invoice.payable

FieldTypeDescription
payment_typestringfull-amount or partial
payable_amount_typestringpercentage or fixed_amount
payable_amountnumberAmount payable

If payment_type, payable_amount_type and payable_amount are not all supplied, the defaults full-amount, fixed_amount and the invoice total are used.

How totals are calculated: subtotal is the sum of qty x rate over the items; the discount is applied to the subtotal; the selected taxes (sum of their rates) are applied to the discounted amount. A line with its own taxes array uses those taxes instead, with the discount allocated pro-rata across lines.

⚠️

Paid (4) and Canceled (8) invoices cannot be edited. The request returns 422 with { "msg": "Paid or Canceled Invoice cannot be edited" }.

Example Request

curl -X PUT "https://public-api.taskip.net/api/public-v1/invoice/157" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json" \ -d '{ "invoice": { "id": 157, "contacts": 45, "subject": "Q1 Marketing Services", "issue_date": "2024-01-25", "due_date": "2024-03-01", "currency": "USD", "items": [ { "name": "Social Media Management", "qty": 3, "rate": 850, "label": "Month", "service_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }, { "name": "Content Creation", "qty": 10, "rate": 150, "label": "Post", "package_id": 12 } ], "discount": 5, "discount_type": "percent", "tax": [1, 3], "notes": [ { "title": "Payment Terms", "description": "Payment due within 30 days", "enable": true } ], "payable": { "payment_type": "full-amount", "payable_amount_type": "fixed_amount", "payable_amount": 4050 } } }'

Example Response

Status: 200 OK

{ "msg": "Invoice update success" }

Errors: 404 { "msg": "Invoice not found" }; 422 { "error": { "invoice.id": ["..."] } } for validation failures.


Delete an Invoice

DELETE /api/public-v1/invoice/{id}

Path Parameters

ParameterTypeRequiredDescription
idinteger or stringYesInvoice ID or invoice number
⚠️

Warning: Deleting an invoice also removes its payment records. This action cannot be undone through the API.

Example Request

curl -X DELETE "https://public-api.taskip.net/api/public-v1/invoice/157" \ -H "X-Secret-Key: your-secret-key-here"

Example Response

{ "msg": "Invoice Deleted Successfully", "status": 200 }

A missing invoice returns 404 with { "status": 404, "msg": "Invoice not found" }.


Bulk Actions on Invoices

Perform an action on up to 1000 invoices at once.

POST /api/public-v1/invoice/bulk-actions

Request Body

FieldTypeRequiredDescription
idsarray of integerYesNumeric invoice IDs (1 to 1000)
actionintegerYes1 = send to client, 2 = delete, 3 = update status
statusintegerFor action 3New status applied to every invoice (see Value Reference)
partialnumberFor status 5Partial payment amount (in currency units)
invoiceHtmlstringFor action 1HTML rendered to PDF for the email
template_idintegerFor action 1Custom email template ID (see the note under Send Invoice to Client)
sent_modestringNoschedule to schedule instead of sending immediately (see Send Invoice to Client)
schedule_typeintegerWith scheduleSchedule type

Action 1 is limited to 10 bulk-send requests per minute. Unknown action values return 422.

Example Request - Mark Several Invoices as Paid

curl -X POST "https://public-api.taskip.net/api/public-v1/invoice/bulk-actions" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json" \ -d '{ "ids": [160, 161, 162], "action": 3, "status": 4 }'

Example Request - Delete

curl -X POST "https://public-api.taskip.net/api/public-v1/invoice/bulk-actions" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json" \ -d '{ "ids": [155, 156], "action": 2 }'

Example Response

{ "msg": "Invoice bulk actions successful" }

An unknown action returns 422 with { "msg": "Invoice bulk actions not found" }. Exceeding the send limit returns 429 with { "msg": "Too many send-to-client requests. Please try again later." }.


Update Invoice Status

POST /api/public-v1/invoice/{id}/status-update

Path Parameters

ParameterTypeRequiredDescription
idinteger or stringYesInvoice ID or invoice number

Request Body

FieldTypeRequiredDescription
statusintegerYesNew status (0-10, see Value Reference). Must be a valid invoice status code, otherwise 422
partialnumberFor status 5Partial payment amount in currency units (e.g. 250.50). Optional numeric >= 0 in general; for status 5 it must be greater than 0 and not exceed the amount still due

Setting status 4 (Paid) records the payment time. Setting status 5 (Partially Paid) records a new partial payment of partial.

Example Request

curl -X POST "https://public-api.taskip.net/api/public-v1/invoice/157/status-update" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json" \ -d '{ "status": 5, "partial": 1000 }'

Example Response (Status 201)

{ "message": "Invoice status updated", "partial_paid_amount": 1000, "due_amount": 2300, "activities": [ { "id": 412, "user": { "id": 1, "first_name": "Admin", "last_name": "User" }, "subject_type": "Modules\\Invoice\\Models\\Invoice", "task": "recorded a partial payment", "status": 5, "type": "payment", "created_at": "2024-01-26T14:30:00.000000Z", "updated_at": "2024-01-26T14:30:00.000000Z" } ] }

Error Responses

For validation problems on a partial payment the response body is a plain JSON string with status 422:

"Partial payment amount exceeds the due amount."

Other possible strings: "Partial payment amount is invalid.". These errors roll back the change, so nothing is recorded. A missing or non-numeric status, an unknown status code, or a negative/non-numeric partial returns 422 in the standard Laravel validation shape (message / errors). A missing invoice returns 404 with { "msg": "Invoice not found" }.


Publish/Unpublish Invoice

Publish an invoice to generate a public shareable link, or remove that link.

POST /api/public-v1/invoice/publish/{id}

Path Parameters

ParameterTypeRequiredDescription
idinteger or stringYesInvoice ID or invoice number

Request Body

FieldTypeRequiredDescription
actionTypeintegerYes1 = publish, 0 = unpublish

Publishing sets the invoice status to Sent. Publishing an already published invoice returns the existing link (and moves a Draft invoice to Sent). Only workspace administrators can publish/unpublish; other users receive an error.

Example Request

curl -X POST "https://public-api.taskip.net/api/public-v1/invoice/publish/157" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json" \ -d '{ "actionType": 1 }'

Example Response

{ "msg": "Invoice published successfully", "slug": "https://your-workspace-link/public/your-tenant/invoice/q1-marketing-services-9b1f2c6e-..." }

Other messages: Invoice already published (with slug) and Invoice unpublished (no slug). The slug field in the response is the full public URL.


Update Payment Gateway

Select the payment gateway used for an invoice.

POST /api/public-v1/invoice/{id}/payment-gateway

Path Parameters

ParameterTypeRequiredDescription
idintegerYesNumeric invoice ID

Request Body

FieldTypeRequiredDescription
payment_gatewaystringYesOne of stripe, paypal, razor, manual, mollie, xendit, fastspring

The value is stored as <gateway>_payment (for example stripe becomes stripe_payment), which is what appears in payment_gateway on the invoice object. Any other value returns an “Unknown payment gateway” error.

Example Request

curl -X POST "https://public-api.taskip.net/api/public-v1/invoice/157/payment-gateway" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json" \ -d '{ "payment_gateway": "stripe" }'

Example Response

{ "msg": "Payment gateway updated successfully" }

Set Up Recurring Payments

Configure recurring billing for an invoice.

POST /api/public-v1/invoice/{id}/recurring

Path Parameters

ParameterTypeRequiredDescription
idintegerYesNumeric invoice ID

Request Body

FieldTypeRequiredDescription
is_payment_reccuringbooleanYesEnable/disable recurring billing (note the spelling)
recurring_untilstringYesEnd date in d-m-Y format, e.g. 31-12-2024
recurring_typestringYesRecurrence type (free text; e.g. monthly)

Example Request

curl -X POST "https://public-api.taskip.net/api/public-v1/invoice/157/recurring" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json" \ -d '{ "is_payment_reccuring": true, "recurring_until": "31-12-2024", "recurring_type": "monthly" }'

Example Response

{ "msg": "Recurring payment details updated." }

Validation failures return 422 in the standard Laravel shape (message, errors).


Download Invoice PDF

Download a PDF version of an invoice.

GET /api/public-v1/invoice/{id}/download

Path Parameters

ParameterTypeRequiredDescription
idintegerYesNumeric invoice ID

Example Request

curl -X GET "https://public-api.taskip.net/api/public-v1/invoice/157/download" \ -H "X-Secret-Key: your-secret-key-here" \ --output invoice-157.pdf

JavaScript Example

const response = await fetch('https://public-api.taskip.net/api/public-v1/invoice/157/download', { method: 'GET', headers: { 'X-Secret-Key': 'your-secret-key-here' } }); if (response.ok) { const blob = await response.blob(); const url = window.URL.createObjectURL(blob); const a = document.createElement('a'); a.href = url; a.download = 'invoice-157.pdf'; a.click(); }

Response

Returns a PDF file download named invoice-<dd-mm-yy>.pdf. No query parameters are supported. If no invoice exists with the given ID, the API returns 422 with { "error": { "msg": ["Invoice not found"] } }.


Send Invoice to Client

Email an invoice to the client, or schedule the email relative to the due date.

⚠️

This endpoint is rate limited to 10 requests per minute. In addition, the same invoice can only be emailed a limited number of times in a short period; exceeding it returns 429.

POST /api/public-v1/invoice/sent/{id}

Path Parameters

ParameterTypeRequiredDescription
idinteger or stringYesInvoice ID or invoice number

Request Body

FieldTypeRequiredDescription
typestringYesMust be invoice. Any other value returns 422
invoiceHtmlstringYes (immediate send)HTML of the invoice rendered to the PDF attached to the email
template_idintegerNoID of a custom email template. If omitted (or null), the default invoice email is sent; if supplied, the custom template is used
sent_modestringNoOnly schedule is accepted: schedules the email instead of sending now
schedule_typeinteger (0-7)Required when sent_mode is schedule0 on due date, 1 3 days after, 2 7 days after, 3 40 days after, 4 1 month after, 5 7 days before, 6 40 days before, 7 3 days before (relative to the due date)

The email is sent to the invoice’s contact (no email is dispatched if the invoice has no contact user). A public share link is created automatically if the invoice was not yet published, and the invoice status is set to Sent. With sent_mode set to schedule the invoice must have a due date that is not in the past, and the chosen “before” schedule must not already have passed.

Example Request

curl -X POST "https://public-api.taskip.net/api/public-v1/invoice/sent/157" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json" \ -d '{ "type": "invoice", "invoiceHtml": "<html><body><h1>Invoice INV-2024-157</h1></body></html>", "template_id": 4 }'

Example Response

{ "msg": "Invoice sent successfully" }

When scheduled, the message is Invoice scheduled successfully. Invalid input (type missing or not invoice, sent_mode other than schedule, schedule_type missing or outside 0-7 when scheduling) returns 422 in the standard Laravel validation shape (message / errors). Scheduling problems (empty due date, due date in the past, or an already-passed “before” schedule) return 422 with { "status": 422, "msg": "..." }. When the per-document email limit is hit, 429 is returned with the limiter message in msg. A missing invoice returns 404 with { "status": 404, "msg": "Invoice not found" }.


Error Responses

Common Error Codes

Status CodeError TypeDescription
401UnauthorizedInvalid or missing X-Secret-Key
403ForbiddenPlan or module access restriction
404Not FoundInvoice not found
422Validation ErrorRequest data failed validation, or the invoice cannot be edited
429Too Many RequestsRate limit exceeded

Validation Error Shapes

Create and update requests use:

{ "error": { "subject": ["The subject field is required."], "contact_id": ["Select exactly one of contact, lead, or company to bill."] } }

Bulk-actions, publish and recurring requests use the standard Laravel shape:

{ "message": "The action field is required.", "errors": { "action": ["The action field is required."] } }

Best Practices

Invoice Management

  1. Create then update: create the invoice, then use update to attach taxes, notes, recurring/payable settings and server-calculated totals.
  2. One billing party: provide exactly one of contact, lead or company.
  3. Pick a number you control: invoice_no is frozen at creation; use a non-numeric value if you want to keep it (numeric values are replaced by a random code).
  4. Amounts: send create-time amounts in cents; read amounts back in currency units.

Workflow

  1. Publish before sharing links: only published invoices have a public slug link.
  2. Record payments through status-update: use status 5 with partial for part payments and 4 for full payment.
  3. Respect rate limits: sending is limited to 10 requests per minute.
Last updated on