Invoicing API

A complete server-side accounts-receivable API. Create customers, draft invoices, post and email them, record payments, issue refunds and credit notes, run recurring templates, and pull a live AR aging report. Every endpoint is multi-tenant, scope-gated, auditable, and idempotency-aware.

Overview

The Invoicing API is the same surface our own dashboard uses. Every action a member can perform in the app, you can perform from your backend with a tenant-scoped API key. Mutations write an immutable audit log row, emit a signed webhook, and increment the per-tenant api_calls_per_month quota for your plan.

This page documents 21 endpoints across customers, invoices, payments, refunds, credit notes, recurring templates, and reporting. For Stripe-hosted Checkout sessions and no-code Payment Links, see the separate Payments API.

Auth & base URL

Generate API keys in the SoftSolz app at Developers → API keys. Pick the scopes the key needs (see below) and copy the secret once - it is hashed at rest and can never be revealed again.

Scopes

Every endpoint requires one of these scopes on the calling key. A wildcard service.invoicing.* grants all of them.

Response envelope

Every successful response uses the same envelope so client code can be uniform.

// Single object (GET /resource/:id, POST /resource)
{ "data": { "id": 42, ... } }

// Paginated list (GET /resource?limit=&offset=)
{ "data": [ ... ], "meta": { "limit": 50, "offset": 0, "has_more": false } }

Every response also carries a Softsolz-Request-Id header. Keep it in your logs - support uses it to trace your request through our systems.

Errors

Errors use the same envelope, with HTTP status set to the right 4xx / 5xx code.

{
  "error": {
    "code": "bad_request",
    "message": "amount is required and must be a positive number.",
    "details": { ... }       // optional, per-endpoint shape
  }
}

Idempotency

Every mutating endpoint accepts an optional Idempotency-Key request header. Replay the same key with the same body and you get the original response back; replay it with a different body and you get a 409 idempotency_key_conflict. Keys live for 24 hours.

Idempotency-Key: 11111111-2222-3333-4444-555555555555

Use a UUIDv4 per logical operation. Re-use the same key across network retries; never re-use it across unrelated operations.

Sandbox keys

A key prefixed sk_test_ always routes to your sandbox tenant. Sandbox tenants have their own data, their own subscription state (paid services auto-activate), and never hit real Stripe / email side-effects. Swap to sk_live_ in production with no other code changes.

Customers

List customers

GET /customers?search=&is_active=&limit=&offset= · scope service.invoicing.customers.view

Returns a paginated list. limit defaults to 50, max 200. search matches display_name or email (case-insensitive). is_active accepts true / false.

Get one customer

GET /customers/:id · scope service.invoicing.customers.view

Create a customer

POST /customers · scope service.invoicing.customers.manage · idempotent

curl -X POST https://app.softsolz.uk/api/v1/services/invoicing/customers \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "display_name": "Acme Coyote Ltd",
    "email": "ap@acme.example",
    "billing_address_line1": "1 Mesa Lane",
    "billing_city": "Tucson",
    "billing_country": "GB",
    "default_currency": "GBP",
    "default_payment_terms_days": 14
  }'

Request body fields:

Update a customer

PUT /customers/:id · scope service.invoicing.customers.manage

Send only the fields you want to change. To enable optimistic concurrency, include the expected_updated_at returned by the previous GET; if a teammate edited the row in the meantime you get a 409 STALE_VERSION.

Archive a customer

DELETE /customers/:id · scope service.invoicing.customers.manage

Soft-archive (flips is_active to false). Returns 409 if the customer has open invoices - void or settle them first.

Issue a customer-portal token

POST /customers/:id/portal-token · scope service.invoicing.customer_portal.manage · idempotent

Returns a short-lived token + hosted URL the customer can use to view their invoices and pay outstanding balances without an account.

Invoices

List invoices

GET /invoices?status=&customer_id=&date_from=&date_to=&limit=&offset= · scope service.invoicing.invoices.view

status ∈ draft | sent | viewed | partially_paid | paid | overdue | void | written_off.

Get one invoice

GET /invoices/:id · scope service.invoicing.invoices.view

Returns the invoice header, every line, payment history, and status-change history. The payments[] array carries the id values you need when issuing a refund.

Create a draft invoice

POST /invoices · scope service.invoicing.invoices.create · idempotent

curl -X POST https://app.softsolz.uk/api/v1/services/invoicing/invoices \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customer_id": 42,
    "currency": "GBP",
    "due_date": "2026-06-30",
    "payment_method": "bank_transfer",
    "bank_details": "Bank: Test Bank\nAccount: 12345678\nSort: 12-34-56",
    "lines": [
      { "description": "Consulting", "quantity": 2, "unit_price": 150, "tax_rate": 0.2 },
      { "description": "Setup fee",  "quantity": 1, "unit_price":  50, "tax_rate": 0   }
    ]
  }'

Request body fields:

Line item fields (each entry in lines): description (string, required), quantity (number > 0, required), unit_price (number in major currency units, e.g. 150.00, required), tax_rate (number, line tax percent where 20 = 20%; ignored when header_tax_rate_pct is set), account_code (string, defaults to "sales").

Update a draft invoice

PUT /invoices/:id · scope service.invoicing.invoices.create

Allowed only while status = 'draft'. Send the full lines array to replace all line items, or omit it to keep them. Supports expected_updated_at for optimistic concurrency.

Download invoice PDF

GET /invoices/:id/pdf · scope service.invoicing.invoices.view

Returns either a binary PDF stream (Content-Type: application/pdf) or a JSON { "url": "https://…" } pre-signed link when the PDF is cached in object storage.

Invoice lifecycle

draft  ──post──▶  sent / viewed  ──mark-paid──▶  partially_paid ──▶ paid
                     │                                                │
                     ├──remind──▶ same status                         │
                     ├──refund──▶ partially_paid ◀──────────────────-─┘
                     └──void──▶  void          (also from draft after post)

Post a draft invoice

POST /invoices/:id/post · scope service.invoicing.invoices.post · idempotent

Finalises the invoice number, locks line edits, and makes it eligible for sending and payment. May route through an approval policy if your tenant has one configured; in that case the response carries { pending_approval: true, instance: { id, … } } and the invoice remains in draft until the approval is decided.

Email the invoice

POST /invoices/:id/send · scope service.invoicing.invoices.send · idempotent

Sends the invoice email with the PDF attached (and the hosted-pay link if Stripe is set up). Status flips to sent.

Send a payment reminder

POST /invoices/:id/remind · scope service.invoicing.reminders.manage · idempotent

Sends a follow-up email. Status is unchanged.

Void the invoice

POST /invoices/:id/void · scope service.invoicing.invoices.void · idempotent

Body: { "reason": "Customer cancelled" } (optional). Voids any payment allocations. May route through an approval policy if configured.

Record a payment

POST /invoices/:id/mark-paid · scope service.invoicing.payments.record · idempotent

Response carries the new payment id - keep it if you plan to refund it later:

{ "data": { "paymentId": 7843, "invoiceId": 921, "finalStatus": "partially_paid" } }

Posts a partial payment if amount < outstanding balance, full payment if equal, and rejects (400) if it exceeds the outstanding by more than a rounding cent. Posting also fires invoicing.invoice.paid on the first transition into paid.

Request body fields:

Refunds

POST /refunds · scope service.invoicing.refunds.create · idempotent

Shrinks amount_paid, rolls invoice status back (paid → partially_paid → sent / overdue / draft), and fires invoicing.refund.issued. May route through an approval policy.

Credit notes

POST /credit-notes · scope service.invoicing.credits.create · idempotent

Allocates a CN-#### credit-note number, applies the amount against amount_paid, and emits invoicing.credit_note.issued.

Recurring invoice templates

List templates

GET /recurring · scope service.invoicing.recurring.manage

Create a template

POST /recurring · scope service.invoicing.recurring.manage

The scheduler generates a new invoice from the template at every cadence tick. Generated invoices appear under the customer's invoice list and trigger the usual create/post/sent webhooks.

AR aging report

GET /reports/ar-aging?as_of=YYYY-MM-DD · scope service.invoicing.ar.aging.view

Buckets every outstanding invoice into current, 1-30, 31-60, 61-90, 90+ based on days past due as of the supplied date (defaults to today). Returns per-customer and per-tenant totals.

Webhook events

Register a webhook endpoint in Developers → Webhooks and subscribe to any of these events. Payloads are signed with HMAC-SHA256 - see Webhooks for the signing scheme and retry policy.