REST API v1

API Reference

The InvoiceMee API lets you create invoices, manage billing profiles, automate recurring charges, and integrate invoice workflows directly into your own products. Every action available in the dashboard is also available via the API.

bolt

Sanctum Tokens

Authenticate once, use your bearer token on every request.

data_object

JSON everywhere

All requests and responses are JSON. Use Accept: application/json.

policy

Policy enforced

Every endpoint checks ownership and company membership — no accidental data leaks.

What you can build

receipt_long

Create & manage invoices

Draft, approve, send, and mark invoices paid — full lifecycle control.

autorenew

Recurring billing

Set up templates that auto-generate child invoices on any schedule.

transform

Quote to invoice

Programmatically convert a quote to a live invoice in a single POST.

picture_as_pdf

PDF generation

Trigger PDF renders on demand and download via signed URL.

group

Multi-company management

Scope all operations to a company or organisation context.

link

Shareable invoice links

Every invoice has a public, unauthenticated view URL for your clients.

Quickstart

Three steps to send your first invoice via the API.

1

Get an API token

POST /api/login

curl -X POST https://yourdomain.com/api/login \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"secret","device_name":"my-app"}'

→ {"token":"1|aBcDeFgHiJkLmN..."}
2

Create an invoice

POST /api/invoices

curl -X POST https://yourdomain.com/api/invoices \
  -H "Authorization: Bearer 1|aBcDeFg..." \
  -H "Content-Type: application/json" \
  -d '{
    "label": "INV-001",
    "invoicer_id": 1,
    "invoice_recipient_id": 3,
    "invoicer_payment_detail_id": 2,
    "currency": "USD",
    "items": [{
      "label": "Web Development",
      "unit": "hour",
      "quantity": 20,
      "price": 150.00,
      "tax_percentage": 20,
      "discount_percentage": false,
      "price_includes_tax": false,
      "price_includes_discount": false,
      "include": true
    }]
  }'
3

Send it to your client

POST /api/invoices/{id}/send

curl -X POST https://yourdomain.com/api/invoices/42/send \
  -H "Authorization: Bearer 1|aBcDeFg..." \
  -H "Content-Type: application/json" \
  -d '{"template":"invoice-issued"}'

→ {"message":"Invoice email queued successfully."}

Authentication

InvoiceMee uses Laravel Sanctum for API authentication. Tokens are per-device and can be revoked at any time. There are no OAuth flows — just a plain token exchange.

Token lifecycle

POST /api/login
Get token
Bearer header
Use on all requests
POST /api/logout
Revoke when done

Base URL & Headers

Base URL

https://yourdomain.com/api

Required headers

Authorization Bearer {your_token}

Required for all protected endpoints

Accept application/json

Always — ensures JSON error responses

Content-Type application/json

Required for POST/PUT requests

Response format

All successful responses wrap data in a data key. Collections include links and meta for pagination.

Single resource

{"data": {"id": 42, "label": "INV-001", ...}}

Paginated collection

{
  "data": [{...}, {...}],
  "links": {"first":...,"next":...},
  "meta": {"current_page":1,"total":47}
}

Validation error (422)

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

Errors & Rate Limits

HTTP status codes

200 OK — request succeeded
201 Created — resource created
204 No Content — deleted successfully
401 Unauthenticated — missing or invalid token
403 Forbidden — policy check failed (wrong company/org)
404 Not found — resource doesn't exist or isn't yours
422 Validation error — check the errors field
429 Rate limit exceeded — slow down
500 Server error — contact support

Rate limits

Standard endpoints 60 req/min
Invoice send email 1 req/min per invoice
PDF regeneration 10 req/min

Rate limit headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
Retry-After: 42  (on 429 only)
lock

Full reference requires login

All endpoint schemas, request parameters, and code examples are available to authenticated users.

Sign In

Auth Endpoints

POST /api/login

Exchange credentials for a Sanctum API token. No authentication required on this endpoint.

Field Type Required Description
email string required The user's registered email address
password string required The user's password
device_name string required A label for this token (e.g. "mobile-app", "ci-server"). Used in token management.

Request

curl -X POST https://yourdomain.com/api/login \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"secret","device_name":"my-app"}'

Response

{"token":"1|aBcDeFgHiJkL...","user":{"id":1,"name":"Jane Doe","email":"you@example.com"}}
POST /api/logout

Revoke the currently active bearer token. The token is permanently deleted and cannot be reused.

Request

curl -X POST https://yourdomain.com/api/logout \
  -H "Authorization: Bearer 1|aBcDeFg..." \
  -H "Accept: application/json"

Response

{"message":"Logged out successfully"}
GET /api/me

Return the profile of the currently authenticated user.

Request

curl https://yourdomain.com/api/me \
  -H "Authorization: Bearer 1|aBcDeFg..." \
  -H "Accept: application/json"

Response

{"id":1,"name":"Jane Doe","email":"you@example.com","created_at":"2025-01-01T00:00:00Z"}

Invoices

Lifecycle & types

draft approved sent paid scheduled due cancelled declined
invoice quote recurring template

Transition: draft → approved → sent → paid. Quotes can be converted to invoices. Recurring templates auto-generate child invoices on schedule.

GET /api/invoices

List all invoices across all companies you own. Results are paginated (25 per page). Filter by status or type using query parameters.

Field Type Required Description
status string optional Filter by status: draft, approved, sent, paid, scheduled, due, cancelled, declined
type string optional Filter by type: invoice, quote, recurring, template

Request

curl "https://yourdomain.com/api/invoices?status=draft&type=invoice" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Response

{"data":[{"id":1,"label":"INV-001","status":"draft","type":"invoice","total":3600.00,"currency":"USD"}],"meta":{"total":3,"current_page":1}}
POST /api/invoices

Create a new invoice, quote, or recurring template. Optionally include line items and member access rules in the same request.

Field Type Required Description
label string required Human-readable invoice number or label (e.g. INV-2025-001)
invoicer_id integer required ID of the invoicer (billing profile) issuing this invoice
invoice_recipient_id integer required ID of the recipient being billed
invoicer_payment_detail_id integer required ID of the payment detail record (bank/account info shown on the PDF)
currency string required ISO 4217 code, 3 chars (e.g. USD, EUR, GBP, HUF)
type enum optional invoice | quote | recurring | template (default: invoice)
status enum optional draft | scheduled | sent | paid | approved | cancelled | declined (default: draft)
scheduled_date date optional Issue date (YYYY-MM-DD). Defaults to today.
due_date date optional Payment due date — must be ≥ scheduled_date
recurring enum optional Required when type=recurring: daily | weekly | monthly | quarterly | yearly
period string optional Billing period label, e.g. "2025-01-01 - 2025-01-31"
description string optional Internal notes (not shown to client)
invoice_parent_id integer optional Parent invoice ID — links a recurring child to its template
items array optional Line item objects (see sub-fields below)
items.*.label string required Name of the line item
items.*.unit enum required hour | service | product | pcs
items.*.quantity numeric required Quantity (0.01 – 9999)
items.*.price numeric required Unit price (before tax/discount unless flags set)
items.*.tax_percentage numeric required Tax as a percentage (e.g. 20 for 20%)
items.*.discount_percentage boolean required true = discount field is %, false = fixed amount
items.*.discount numeric conditional Discount amount or percentage. Required when discount_percentage is set.
items.*.price_includes_tax boolean required Whether the unit price already includes tax
items.*.price_includes_discount boolean required Whether the unit price already includes the discount
items.*.include boolean required Whether to include this item in the invoice total
members array optional Team member access control
members.*.member_id integer required User ID of the team member
members.*.view_invoice boolean required Can the member view this invoice?
members.*.receive_invoice boolean required Does the member receive email notifications?
members.*.action_invoice boolean optional Can the member approve/pay/cancel this invoice?

Request

curl -X POST https://yourdomain.com/api/invoices \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "INV-2025-001",
    "invoicer_id": 1,
    "invoice_recipient_id": 3,
    "invoicer_payment_detail_id": 2,
    "currency": "USD",
    "type": "invoice",
    "scheduled_date": "2025-06-01",
    "due_date": "2025-06-30",
    "items": [{
      "label": "Web Development",
      "unit": "hour",
      "quantity": 40,
      "price": 150.00,
      "tax_percentage": 20,
      "discount_percentage": false,
      "price_includes_tax": false,
      "price_includes_discount": false,
      "include": true
    }]
  }'

Response

{"data":{"id":42,"label":"INV-2025-001","status":"draft","type":"invoice","currency":"USD","subtotal":6000.00,"tax":1200.00,"total":7200.00,"items":[...]}}
GET /api/invoices/{id}

Retrieve a single invoice with its invoicer, recipient, payment details, line items, payments, and history.

Field Type Required Description
id integer required Invoice ID

Request

curl https://yourdomain.com/api/invoices/42 \
  -H "Authorization: Bearer {token}"

Response

{"data":{"id":42,"label":"INV-2025-001","status":"draft","total":7200.00,"invoicer":{...},"recipient":{...},"items":[...],"payments":[],"history":[]}}
PUT /api/invoices/{id}

Update an invoice. Only allowed while the invoice is in draft or scheduled state. Accepts the same fields as POST /api/invoices.

Field Type Required Description
id integer required Invoice ID
... — optional Any fields from POST /api/invoices (all optional on update)

Request

curl -X PUT https://yourdomain.com/api/invoices/42 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"due_date":"2025-07-15","description":"Updated payment terms: 30 days net"}'

Response

{"data":{"id":42,"due_date":"2025-07-15","description":"Updated payment terms: 30 days net",...}}
DELETE /api/invoices/{id}

Permanently delete an invoice and its line items. This action cannot be undone.

Field Type Required Description
id integer required Invoice ID

Request

curl -X DELETE https://yourdomain.com/api/invoices/42 \
  -H "Authorization: Bearer {token}"

Response

204 No Content
POST /api/invoices/{id}/approve

Approve a quote, advancing it to approved status. A PDF is generated automatically on approval. Optionally back-date the approval timestamp.

Field Type Required Description
id integer required Invoice ID
approved_at datetime optional Approval timestamp in ISO 8601. Defaults to now.

Request

curl -X POST https://yourdomain.com/api/invoices/42/approve \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"approved_at":"2025-06-02T09:00:00Z"}'

Response

{"data":{"id":42,"status":"approved","approved_at":"2025-06-02T09:00:00Z",...}}
POST /api/invoices/{id}/pay

Record a payment against an invoice. Supports partial payments — call multiple times until the full amount is covered. Status changes to paid when the balance reaches zero.

Field Type Required Description
id integer required Invoice ID
amount numeric required Amount paid. Min 0.01. Must not exceed the remaining unpaid balance.
paid_date date optional Payment date (YYYY-MM-DD). Defaults to today.
reference string optional Bank reference, transaction ID, or notes about this payment
payment_method string optional e.g. bank_transfer, card, cash, crypto

Request

curl -X POST https://yourdomain.com/api/invoices/42/pay \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"amount":7200.00,"reference":"TXN-987654","payment_method":"bank_transfer"}'

Response

{"data":{"id":42,"status":"paid","payments":[{"amount":7200.00,"reference":"TXN-987654","paid_date":"2025-06-15"}]}}
POST /api/invoices/{id}/cancel

Cancel an invoice. Status changes to cancelled. No request body needed.

Field Type Required Description
id integer required Invoice ID

Request

curl -X POST https://yourdomain.com/api/invoices/42/cancel \
  -H "Authorization: Bearer {token}"

Response

{"data":{"id":42,"status":"cancelled",...}}
POST /api/invoices/{id}/send

Queue a transactional email to the invoice recipient. Choose from the built-in templates below. Rate limited to 1 send per invoice per minute.

Field Type Required Description
id integer required Invoice ID
template enum required One of: quote | invoice-issued | invoice-reminder | invoice-due | invoice-due-reminder | estimate-actioned | invoice-paid
custom_message string optional Additional text appended below the template body in the email

Request

curl -X POST https://yourdomain.com/api/invoices/42/send \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"template":"invoice-issued","custom_message":"Please review at your earliest convenience."}'

Response

{"message":"Invoice email queued successfully."}
GET /api/invoices/{id}/download

Returns a direct URL to the invoice PDF file stored in media library. PDF is generated on first approval — call /regenerate-pdf if you need a fresh copy.

Field Type Required Description
id integer required Invoice ID

Request

curl https://yourdomain.com/api/invoices/42/download \
  -H "Authorization: Bearer {token}"

Response

{"download_url":"https://yourdomain.com/storage/media/42/invoice.pdf","expires_at":null}
POST /api/invoices/{id}/convert

Convert an invoice to a different type. A new record is created preserving all line items; the original is untouched. Useful for turning quotes into billable invoices or creating recurring templates.

Field Type Required Description
id integer required Source invoice ID
type enum required Target type: invoice | quote | recurring | template
scheduled_date date optional Issue date for the new record (YYYY-MM-DD)
due_date date optional Due date for the new record
recurring enum optional Required when converting to recurring: daily | weekly | monthly | quarterly | yearly
period string optional Billing period for the new record

Request

curl -X POST https://yourdomain.com/api/invoices/42/convert \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"type":"recurring","recurring":"monthly","scheduled_date":"2025-07-01"}'

Response

{"data":{"id":43,"type":"recurring","label":"INV-2025-001","recurring":"monthly",...}}
POST /api/invoices/{id}/create-next

Manually trigger the next invoice generation from a recurring template. The scheduler does this automatically based on the recurring interval, but you can also trigger it on demand.

Field Type Required Description
id integer required Recurring template invoice ID

Request

curl -X POST https://yourdomain.com/api/invoices/43/create-next \
  -H "Authorization: Bearer {token}"

Response

{"data":{"id":44,"type":"invoice","invoice_parent_id":43,"label":"INV-2025-001","status":"draft",...}}
POST /api/invoices/{id}/set-schedule-date

Set or update the scheduled (issue) date of an invoice. The scheduler uses this to determine when to transition the invoice from scheduled to active.

Field Type Required Description
id integer required Invoice ID
scheduled_date date required New issue date (YYYY-MM-DD)
due_now boolean optional If true, also immediately transitions the invoice to due status

Request

curl -X POST https://yourdomain.com/api/invoices/42/set-schedule-date \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"scheduled_date":"2025-07-01"}'

Response

{"data":{"id":42,"scheduled_date":"2025-07-01","status":"scheduled",...}}
POST /api/invoices/{id}/set-due-date

Update the payment due date. Must be on or after the scheduled date.

Field Type Required Description
id integer required Invoice ID
due_date date required New due date (YYYY-MM-DD)

Request

curl -X POST https://yourdomain.com/api/invoices/42/set-due-date \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"due_date":"2025-07-31"}'

Response

{"data":{"id":42,"due_date":"2025-07-31",...}}
POST /api/invoices/{id}/set-period

Set the billing period label displayed on the invoice PDF and in the dashboard.

Field Type Required Description
id integer required Invoice ID
period string required Period string. Recommended format: "YYYY-MM-DD - YYYY-MM-DD"

Request

curl -X POST https://yourdomain.com/api/invoices/42/set-period \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"period":"2025-06-01 - 2025-06-30"}'

Response

{"data":{"id":42,"period":"2025-06-01 - 2025-06-30",...}}
POST /api/invoices/{id}/regenerate-pdf

Force a fresh PDF render using the current invoice data. The previous file in storage is replaced. Useful after updating line items or invoice details post-approval.

Field Type Required Description
id integer required Invoice ID

Request

curl -X POST https://yourdomain.com/api/invoices/42/regenerate-pdf \
  -H "Authorization: Bearer {token}"

Response

{"data":{"id":42,"pdf_url":"https://yourdomain.com/storage/media/42/invoice.pdf",...}}

Invoicers

Invoicers are your billing profiles — the "from" side of every invoice. Each one stores your legal entity name, address, tax/registration number, logo, and default payment details. A company can have multiple invoicers (e.g. different legal entities or brands).

GET /api/invoicers

List all invoicers across your companies.

Request

curl https://yourdomain.com/api/invoicers \
  -H "Authorization: Bearer {token}"

Response

{"data":[{"id":1,"company_entity":"Acme Ltd","currency":"USD","default":true,...}],...}
POST /api/invoicers

Create a new billing profile / invoicer.

Field Type Required Description
company_id integer required Company this invoicer belongs to
company_entity string required Legal entity / trading name shown on invoices
description string optional Internal description for team reference
company_tax_number string optional VAT / GST / tax registration number
company_registration_number string optional Company registration or incorporation number
company_address string optional Full billing address printed on invoices
currency string optional Default ISO 4217 currency code (3 chars)
tax_rate numeric optional Default tax rate percentage applied to new invoices
default boolean optional Set this as the default invoicer for the company

Request

curl -X POST https://yourdomain.com/api/invoicers \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"company_id":1,"company_entity":"Acme Ltd","currency":"USD","tax_rate":20,"default":true}'

Response

{"data":{"id":1,"company_entity":"Acme Ltd","currency":"USD","default":true,...}}
GET /api/invoicers/{id}

Retrieve a single invoicer with its payment details.

Field Type Required Description
id integer required Invoicer ID

Request

curl https://yourdomain.com/api/invoicers/1 \
  -H "Authorization: Bearer {token}"

Response

{"data":{"id":1,"company_entity":"Acme Ltd","payment_details":[...],...}}
PUT /api/invoicers/{id}

Update a billing profile. Only pass the fields you want to change.

Field Type Required Description
id integer required Invoicer ID
company_id integer required Company this invoicer belongs to
company_entity string required Legal entity / trading name shown on invoices
description string optional Internal description for team reference
company_tax_number string optional VAT / GST / tax registration number
company_registration_number string optional Company registration or incorporation number
company_address string optional Full billing address printed on invoices
currency string optional Default ISO 4217 currency code (3 chars)
tax_rate numeric optional Default tax rate percentage applied to new invoices
default boolean optional Set this as the default invoicer for the company

Request

curl -X PUT https://yourdomain.com/api/invoicers/1 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"company_address":"123 Main St, New York, NY 10001"}'

Response

{"data":{"id":1,"company_address":"123 Main St, New York, NY 10001",...}}
DELETE /api/invoicers/{id}

Delete a billing profile. Cannot delete if invoices reference it.

Field Type Required Description
id integer required Invoicer ID

Request

curl -X DELETE https://yourdomain.com/api/invoicers/1 \
  -H "Authorization: Bearer {token}"

Response

204 No Content

Recipients

Recipients are the clients you bill — the "to" side of every invoice. Each recipient stores the client's entity name, address, tax number, and default billing preferences like hourly rates and currency.

GET /api/recipients

List all invoice recipients across your organisations.

Request

curl https://yourdomain.com/api/recipients \
  -H "Authorization: Bearer {token}"

Response

{"data":[{"id":1,"company_entity":"Client Corp","currency":"EUR",...}],...}
POST /api/recipients

Create a new invoice recipient / client.

Field Type Required Description
company_entity string required Client company or individual name shown on invoices
organisation_id integer required Organisation this recipient belongs to
description string optional Internal notes about this client
company_tax_number string optional Client's VAT / tax registration number
company_registration_number string optional Client's company registration number
company_address string optional Client's billing address
currency string optional Preferred ISO 4217 currency (3 chars)
tax_rate numeric optional Default tax rate for this client
default_hour_rate numeric optional Default hourly rate used when creating time-based invoices for this client
default boolean optional Set as the default recipient for the organisation

Request

curl -X POST https://yourdomain.com/api/recipients \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"company_entity":"Client Corp","organisation_id":2,"currency":"EUR","default_hour_rate":120,"tax_rate":0}'

Response

{"data":{"id":5,"company_entity":"Client Corp","currency":"EUR",...}}
GET /api/recipients/{id}

Retrieve a single recipient.

Field Type Required Description
id integer required Recipient ID

Request

curl https://yourdomain.com/api/recipients/5 \
  -H "Authorization: Bearer {token}"

Response

{"data":{"id":5,"company_entity":"Client Corp","default_hour_rate":120,...}}
PUT /api/recipients/{id}

Update a client's billing details. Only pass fields you want to change.

Field Type Required Description
id integer required Recipient ID
company_entity string required Client company or individual name shown on invoices
organisation_id integer required Organisation this recipient belongs to
description string optional Internal notes about this client
company_tax_number string optional Client's VAT / tax registration number
company_registration_number string optional Client's company registration number
company_address string optional Client's billing address
currency string optional Preferred ISO 4217 currency (3 chars)
tax_rate numeric optional Default tax rate for this client
default_hour_rate numeric optional Default hourly rate used when creating time-based invoices for this client
default boolean optional Set as the default recipient for the organisation

Request

curl -X PUT https://yourdomain.com/api/recipients/5 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"company_address":"456 Park Ave, London EC1A 1BB","default_hour_rate":140}'

Response

{"data":{"id":5,"company_address":"456 Park Ave, London EC1A 1BB","default_hour_rate":140,...}}
DELETE /api/recipients/{id}

Delete a recipient. Cannot delete if invoices reference it.

Field Type Required Description
id integer required Recipient ID

Request

curl -X DELETE https://yourdomain.com/api/recipients/5 \
  -H "Authorization: Bearer {token}"

Response

204 No Content

Companies

Companies are the top-level workspaces. All invoicers, invoices, and team members are scoped to a company. A user can own or be a member of multiple companies.

GET /api/companies

List all companies.

POST /api/companies

Create a new companie.

Field Type Required Description
name string required Company display name
slug string optional URL-friendly identifier (auto-generated if omitted)
GET /api/companies/{id}

Retrieve a single companie.

Field Type Required Description
id integer required Resource ID
PUT /api/companies/{id}

Update an existing companie.

Field Type Required Description
id integer required Resource ID
name string required Company display name
slug string optional URL-friendly identifier (auto-generated if omitted)
DELETE /api/companies/{id}

Delete a companie.

Field Type Required Description
id integer required Resource ID

Organisations

Organisations group recipients together. They sit inside a company and represent client-facing entities or project groups.

GET /api/organisations

List all organisations.

POST /api/organisations

Create a new organisation.

Field Type Required Description
name string required Organisation name
slug string optional URL-friendly identifier (auto-generated if omitted)
company_id integer required Company this organisation belongs to
GET /api/organisations/{id}

Retrieve a single organisation.

Field Type Required Description
id integer required Resource ID
PUT /api/organisations/{id}

Update an existing organisation.

Field Type Required Description
id integer required Resource ID
name string required Organisation name
slug string optional URL-friendly identifier (auto-generated if omitted)
company_id integer required Company this organisation belongs to
DELETE /api/organisations/{id}

Delete a organisation.

Field Type Required Description
id integer required Resource ID