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
| Method | Endpoint | Description |
|---|---|---|
GET | /api/public-v1/invoice | Get all invoices |
POST | /api/public-v1/invoice | Create 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-actions | Bulk operations on invoices |
POST | /api/public-v1/invoice/{id}/status-update | Update invoice status |
POST | /api/public-v1/invoice/publish/{id} | Publish/unpublish invoice |
POST | /api/public-v1/invoice/{id}/payment-gateway | Update payment gateway |
POST | /api/public-v1/invoice/{id}/recurring | Set up recurring payments |
GET | /api/public-v1/invoice/{id}/download | Download 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
| Value | Meaning |
|---|---|
0 | Draft |
1 | Sent |
2 | Pending |
3 | Overdue |
4 | Paid |
5 | Partially Paid |
6 | Void |
7 | Refunded |
8 | Canceled |
9 | Accepted |
10 | Failed |
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/invoiceRequest Headers
X-Secret-Key: your-secret-key-here
Content-Type: application/jsonQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number for pagination |
item | integer | No | Invoices per page (default: 10). 0 returns all invoices without pagination |
search | string | No | Matches 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 |
status | integer | No | Filter by status (0-10, see Value Reference) |
from | string | No | Start date (YYYY-MM-DD). Must be used together with to |
to | string | No | End 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_nois set when the invoice is created and never changes afterwards.generatedIdis the formatted display number, also frozen at creation, so later changes to your numbering settings do not renumber existing invoices.statusis the numeric code from the Value Reference.recurring_untilshows1970-01-01when no recurring end date is set.meta.searchis only present whensearchwas used.- The selected tax details (
taxes,total_tax,global_tax_id,tax_rate) andthemeare not included in public API responses. Taxes are applied when you update an invoice, and they are reflected intotal.
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/invoiceRequest Headers
X-Secret-Key: your-secret-key-here
Content-Type: application/jsonRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
invoice_no | string | Yes | Invoice number; must be unique. A purely numeric value is replaced by a random 10-character uppercase code. The number is frozen once created |
subject | string | Yes | Invoice subject (max 191 characters) |
currency | string | Yes | Currency code (max 191 characters; stored lower-case) |
contact_id | integer | No | Contact ID to bill (must exist) |
lead_id | integer | No | Lead ID to bill (must exist) |
company_id | integer | No | Company ID to bill (must exist) |
project_id | string | No | Folder ID to file the invoice in |
issue_date | string | No | Issue date (YYYY-MM-DD) |
due_date | string | No | Due date (YYYY-MM-DD) |
subtotal | number | No | Subtotal in the smallest currency unit (cents) |
discount | number | No | Discount value |
discount_type | string | No | Discount type (default: percent) |
total | number | No | Total in the smallest currency unit (cents) |
items | string | No | Line items as a JSON-encoded string (see below) |
logo | integer | No | Logo media ID |
signature | integer | No | Signature media ID |
terms | string | No | Invoice terms |
status | integer | No | Only 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)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Item name/description |
qty | number | Yes | Item quantity |
rate | number | Yes | Price per unit |
label | string | No | Item 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
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | Invoice 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
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | Invoice ID or invoice number |
Request Body
Send a JSON object with a single invoice key. The fields below go inside it.
| Field | Type | Required | Description |
|---|---|---|---|
invoice.id | integer | Yes | Invoice ID (must exist) |
invoice.invoice_no | string | No | Accepted but ignored: the invoice number is frozen at creation |
invoice.contacts | integer | No | Contact ID to bill (must exist) |
invoice.lead_id | integer | No | Lead ID to bill (must exist) |
invoice.company_id | integer | No | Company ID to bill (must exist) |
invoice.payment_gateway | string | No | Stored as given, e.g. stripe_payment. Omitting it clears the stored gateway; prefer the Update Payment Gateway endpoint |
invoice.template | integer | No | Template ID (default: 1) |
invoice.subject | string | No | Invoice subject |
invoice.issue_date | string | No | Issue date (YYYY-MM-DD) |
invoice.due_date | string | No | Due date (YYYY-MM-DD) |
invoice.currency | string | No | Currency code |
invoice.items | array | No | Line items (see below) |
invoice.subtotal | number | No | Accepted but ignored: the server recalculates the subtotal from the items |
invoice.total | number | No | Accepted but ignored: the server recalculates the total |
invoice.discount | number | No | Discount value |
invoice.discount_type | string | No | percent or amount (default: percent) |
invoice.tax | array of integer | No | IDs of the global taxes to apply. Multiple taxes can be selected; their rates are added together |
invoice.global_tax_id | integer | No | Legacy single global tax ID; used only when tax is empty |
invoice.tax_rate | number | No | Manual tax rate (0-100); used only when neither tax nor global_tax_id resolves a tax |
invoice.notes | array | No | Notes (see below). Notes missing from the array are deleted |
invoice.recurring_payment | object | No | Recurring settings (see below) |
invoice.payable | object | No | Payable settings (see below) |
invoice.theme | string | No | Accepted (max 191) but not stored |
invoice.logo | integer | No | Logo media ID |
invoice.signature | integer | No | Signature media ID |
invoice.multiple_payment_gateway | array | No | Accepted; 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[]
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | No | Item ID |
name | string | No | Item name |
qty | number | No | Quantity |
rate | number | No | Unit price |
label | string | No | Item label |
tax | number | No | Legacy per-item tax percentage (max 100); used only when the invoice has no tax selection |
taxes | array of integer | No | Global tax IDs that replace the invoice-level taxes for this line only |
service_uuid | string | No | UUID of a service from your service catalog to link to this line (must exist) |
package_id | integer | No | ID 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
| Field | Type | Description |
|---|---|---|
is_payment_reccuring | boolean | Enable recurring billing (note the spelling) |
payment_recurring_type | string | Recurrence type (max 50) |
start_from | date | Start date |
recurring_until | string | End date |
The recurring values are only saved when is_payment_reccuring is true; otherwise they are cleared.
invoice.payable
| Field | Type | Description |
|---|---|---|
payment_type | string | full-amount or partial |
payable_amount_type | string | percentage or fixed_amount |
payable_amount | number | Amount 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
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | Invoice 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-actionsRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
ids | array of integer | Yes | Numeric invoice IDs (1 to 1000) |
action | integer | Yes | 1 = send to client, 2 = delete, 3 = update status |
status | integer | For action 3 | New status applied to every invoice (see Value Reference) |
partial | number | For status 5 | Partial payment amount (in currency units) |
invoiceHtml | string | For action 1 | HTML rendered to PDF for the email |
template_id | integer | For action 1 | Custom email template ID (see the note under Send Invoice to Client) |
sent_mode | string | No | schedule to schedule instead of sending immediately (see Send Invoice to Client) |
schedule_type | integer | With schedule | Schedule 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-updatePath Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | Invoice ID or invoice number |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
status | integer | Yes | New status (0-10, see Value Reference). Must be a valid invoice status code, otherwise 422 |
partial | number | For status 5 | Partial 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
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | Invoice ID or invoice number |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
actionType | integer | Yes | 1 = 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-gatewayPath Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Numeric invoice ID |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
payment_gateway | string | Yes | One 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}/recurringPath Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Numeric invoice ID |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
is_payment_reccuring | boolean | Yes | Enable/disable recurring billing (note the spelling) |
recurring_until | string | Yes | End date in d-m-Y format, e.g. 31-12-2024 |
recurring_type | string | Yes | Recurrence 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}/downloadPath Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Numeric 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.pdfJavaScript 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
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | Invoice ID or invoice number |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Must be invoice. Any other value returns 422 |
invoiceHtml | string | Yes (immediate send) | HTML of the invoice rendered to the PDF attached to the email |
template_id | integer | No | ID of a custom email template. If omitted (or null), the default invoice email is sent; if supplied, the custom template is used |
sent_mode | string | No | Only schedule is accepted: schedules the email instead of sending now |
schedule_type | integer (0-7) | Required when sent_mode is schedule | 0 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 Code | Error Type | Description |
|---|---|---|
401 | Unauthorized | Invalid or missing X-Secret-Key |
403 | Forbidden | Plan or module access restriction |
404 | Not Found | Invoice not found |
422 | Validation Error | Request data failed validation, or the invoice cannot be edited |
429 | Too Many Requests | Rate 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
- Create then update: create the invoice, then use update to attach taxes, notes, recurring/payable settings and server-calculated totals.
- One billing party: provide exactly one of contact, lead or company.
- Pick a number you control:
invoice_nois frozen at creation; use a non-numeric value if you want to keep it (numeric values are replaced by a random code). - Amounts: send create-time amounts in cents; read amounts back in currency units.
Workflow
- Publish before sharing links: only published invoices have a public
sluglink. - Record payments through status-update: use status
5withpartialfor part payments and4for full payment. - Respect rate limits: sending is limited to 10 requests per minute.