Create a sales invoice

POSThttps://<your-url>/api/v2/sales-invoices

MCP id sales-invoices.storeAlso on this path: GET List sales invoices

Creates an invoice header and returns it in the detail view with a Location header.

Token scope: api:write:sales_invoices
Without it: 403 insufficient-token-scope.
Permission: sales_invoices::create
Without it: 403 insufficient-permission.
Feature: Needs the billing feature on your organisation.
Without it: 404 endpoint-not-found.
Rate cost: 1 unit, write bucket. A write costs the same whatever view you ask for.
Also: Accepts Idempotency-Key. Never cached: private, no-store. Unknown body keys are refused, never dropped.

Both are checked, scope first. A token never does more than its user. How access is checked

Request

Example: An invoice for one customer

curl -X POST \
  'https://<your-url>/api/v2/sales-invoices' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <key>' \
  -d '{
    "customer_id": 1,
    "invoice_date": "2026-02-01",
    "due_date": "2026-03-03",
    "reference": "PO-4471",
    "description": "Development work, January 2026"
  }'

const response = await fetch('https://<your-url>/api/v2/sales-invoices', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': '<key>',
  },
  body: JSON.stringify({
    "customer_id": 1,
    "invoice_date": "2026-02-01",
    "due_date": "2026-03-03",
    "reference": "PO-4471",
    "description": "Development work, January 2026"
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('Idempotency-Key', '<key>')
    ->post('https://<your-url>/api/v2/sales-invoices', [
        'customer_id' => 1,
        'invoice_date' => '2026-02-01',
        'due_date' => '2026-03-03',
        'reference' => 'PO-4471',
        'description' => 'Development work, January 2026',
    ]);

import requests
response = requests.request(
    'POST',
    'https://<your-url>/api/v2/sales-invoices',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'Idempotency-Key': '<key>'},
    json={'customer_id': 1, 'invoice_date': '2026-02-01', 'due_date': '2026-03-03', 'reference': 'PO-4471', 'description': 'Development work, January 2026'},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "customer_id": 1,
    "customer": {
      "id": 1
    },
    "project_id": 1,
    "customer_subscription_id": 1,
    "invoice_number": "…",
    "reference": "PO-4471",
    "description": "Development work, January 2026",
    "invoice_date": "2026-02-01",
    "due_date": "2026-03-03",
    "status": "draft",
    "should_email": false
  }
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/idempotency-key-in-flight",
  "title": "Idempotency key in flight",
  "status": 409,
  "detail": "The original request for this Idempotency-Key is still being processed. Retry shortly.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S"
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "3 fields failed validation.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "errors": [
    {
      "pointer": "/date",
      "code": "date_format",
      "detail": "The date does not match the format Y-m-d."
    },
    {
      "pointer": "/minutes",
      "code": "min",
      "detail": "The minutes must be at least 1."
    },
    {
      "pointer": "/description",
      "code": "required",
      "detail": "The description field is required."
    }
  ]
}

18 more fields, listed under Response

It has no rows yet, so subtotal, vat_total and total are 0.00: post each row to sales-invoices/{sales_invoice}/rows afterwards and the totals follow. The invoice number is allocated by the server from the organisation's yearly sequence and cannot be supplied. The server sets the status too: a caller without sales_invoices::finalize creates a pending_approval invoice that a colleague holding that permission must approve in plnnrly; no API endpoint advances it. In an organisation with the accounting integration connected the invoice starts as a draft awaiting the sync, and the customer must be linked to that system or the sync will later fail; in one without it the invoice is local, immediately settled, and never emailed. Send Idempotency-Key to make a retry safe.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

viewstring

Which field set to render.

summarydetaildefault

Request headers

X-Request-Idstringpattern

A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.

Idempotency-Keystring≤ 255

A caller-chosen key that makes this POST safe to retry. Replaying it returns the original response with Idempotency-Replayed: true.

Request body

Unknown keys are refused with 422, naming the key.

customer_idinteger → Customer.idRequired

Customer this invoice is billed to.

invoice_datedate (YYYY-MM-DD)Required

Invoice date, a zone-free calendar date. Newest first is the default sort.

project_idinteger or null → Project.id

Project this invoice was raised for, when it was raised from one.

customer_subscription_idinteger or null → CustomerSubscription.id

Customer subscription this invoice was generated from, when it was generated from a renewal.

due_datedate (YYYY-MM-DD) or null

Date payment is due, a zone-free calendar date. Null when no term was applied.

Must be on or after invoice_date.

referencestring or null≤ 255

The customer's own reference, typically a purchase-order number, reproduced on the invoice.

descriptionstring or null≤ 255

One-line description of what was invoiced.

internal_notesstring or null

Notes for colleagues. Never rendered on the invoice the customer receives.

should_emailboolean

Whether the invoice is emailed to the customer when it syncs. The email is sent through the accounting integration, so it is forced to false in an organisation with no integration configured. Writing it requires sales_invoices::finalize.

Response 201

Returns a SalesInvoice in the detail view.

Headers

ETag: A strong validator of exactly this representation.
Idempotency-Replayed: true when this response was replayed from a stored Idempotency-Key rather than produced by a new write.
Location: The absolute URL of the created or queued resource.
RateLimit: The IETF httpapi-ratelimit-headers form of your remaining allowance on the tightest bucket this request touched.
RateLimit-Policy: The ceiling and window of that bucket, as <limit>;w=<seconds>.
X-Request-Id: The server-generated ULID correlating this response with our logs.

Every response also carries Cache-Control, Vary, X-Content-Type-Options, X-Plnnrly-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Headers and versioning

idinteger

Unique identifier.

customer_idinteger

Customer this invoice is billed to.

customerRef or CustomerSummary

The customer this invoice is billed to. Expanding it with ?include=customer additionally requires the customers::read permission and a token scope covering the customers prefix.

project_idinteger or null

Project this invoice was raised for, when it was raised from one.

customer_subscription_idinteger or null

Customer subscription this invoice was generated from, when it was generated from a renewal.

invoice_numberstring≤ 255Server-assigned

Invoice number, allocated by the server from the organisation's yearly sequence: B-26-00001 for an invoice raised in this flow, L-1234 for one converted from a legacy invoice. It also works in the path: GET sales-invoices/B-26-00001 works. This is the field ?q= searches.

referencestring or null≤ 255

The customer's own reference, typically a purchase-order number, reproduced on the invoice.

descriptionstring or null≤ 255

One-line description of what was invoiced.

invoice_datedate (YYYY-MM-DD)

Invoice date, a zone-free calendar date. Newest first is the default sort.

due_datedate (YYYY-MM-DD) or null

Date payment is due, a zone-free calendar date. Null when no term was applied.

statusstringServer-assigned

Lifecycle status. Resolved by the server on create and never writable: a caller without sales_invoices::finalize creates a pending_approval invoice, and any update by such a caller returns the invoice to pending_approval.

draftpending_approvalsentpaidoverduecancelled

New values may be added.

should_emailboolean

subtotaldecimal (2 dp)Server-assigned

Sum of the row line totals excluding VAT, as a decimal string. Recomputed from the rows; never written directly.

2 decimal places, may be negative

vat_totaldecimal (2 dp)Server-assigned

Sum of the row VAT amounts, as a decimal string. Recomputed from the rows; never written directly.

2 decimal places, may be negative

totaldecimal (2 dp)Server-assigned

Subtotal plus VAT, as a decimal string. Recomputed from the rows; never written directly.

2 decimal places, may be negative

exact_invoice_idstring or null≤ 255Server-assigned

The accounting system's own identifier for this invoice, written by the sync. Not a local id.

exact_journalstring or null≤ 255Server-assigned

Sales journal the invoice is booked in, resolved from the organisation's accounting settings on create. Null in an organisation with no integration configured.

sync_statusstringServer-assigned

How far the invoice has got through the accounting sync. Set on create: local in an organisation with no integration configured, pending otherwise.

pendingsyncedfailedlocal

New values may be added.

sync_errorstring or nullDetail onlyServer-assignedMultiline

Why the last sync attempt failed, verbatim from the accounting system. Null while nothing has failed.

synced_attimestamp (YYYY-MM-DDThh:mm:ssZ) or nullServer-assigned

When the invoice last synced successfully.

sync_attempted_attimestamp (YYYY-MM-DDThh:mm:ssZ) or nullServer-assigned

When the invoice was last handed to the sync, successfully or not.

paid_attimestamp (YYYY-MM-DDThh:mm:ssZ) or nullServer-assigned

When the invoice was settled. Set on create for a local invoice that is immediately definitive; otherwise written when payment is registered.

is_legacybooleanServer-assigned

Whether this invoice was converted from a legacy invoice. Such an invoice is read-only: PATCH and DELETE answer 409 state-conflict with reason locked_by_legacy.

legacy_invoice_idinteger or nullServer-assigned

The id of the legacy invoice this invoice was converted from, so it can be matched with GET /api/v2/invoices. The legacy invoice may since have been removed.