Create an invoice

post

https://sandbox.uk.rootplatform.com/v1/insurance/policies/{policy_id}/invoices

Bundle one or more of a policy's uninvoiced ledger journal entries into an invoice. Select the entries to invoice with the list uninvoiced ledger entries endpoint.

This route always finalises the invoice, so it is returned in open, with its invoice number allocated and its document queued for rendering. There is no way to create a draft invoice over the API. Only the generate_invoice product module action can, by passing auto_finalise: false.

Invoicing is opt-in per organization: unless the invoicing feature flag is enabled for your organization this endpoint returns 403. It additionally requires the policy to have been migrated to Root's current ledger, since invoicing reads and writes ledger journal entries only.

Path Params

policy_id

string

required

Must be a UUID. The unique identifier of the policy to invoice.

Body Params

journal_entry_ids

array of uuids

required

length ≥ 1

The ledger journal entries to invoice, as returned in entry_id by the list uninvoiced ledger entries endpoint. At least one is required. Every entry must belong to the policy and must not already be attached to an invoice.

journal_entry_ids*

type

string

length between 1 and 255

A free-form label passed through to the render template, for example premium. Nothing branches on it: a credit note is signalled by original_invoice_id, not by type.

message

string

length ≤ 5000

A free-text note to the recipient, stored verbatim and handed to the render template.

due_date

date

The date the invoice falls due, as an ISO 8601 date.

reference

string

The invoice number to use. Omit it to have Root allocate the next number in the organization's sequence.

original_invoice_id

uuid

The invoice this one credits. Supplying it makes this invoice a credit note: the referenced invoice moves to refunded, and the new invoice's net total must be negative in ledger terms. Only an open or paid invoice can be credited.

line_item_refund_mappings

array of objects

For a credit note, which original line item each new entry reverses. Populates refunded_by_line_item_id on the original lines so the reversal can be traced per line.

line_item_refund_mappings

line_item_metadata

array of objects

Optional per-line data, keyed to an entry in journal_entry_ids. metadata is an opaque object that Root stores and hands to the render template but never interprets. The product module and template own its shape. Entries with no mapping here get no metadata.

line_item_metadata

Responses

400

Validation error. Examples: a journal entry does not belong to the policy, an entry is already attached to another invoice, journal_entry_ids contains duplicates, or a credit note's net total is not negative.

403

Invoicing is not enabled for the organization, or the caller is missing the invoices:create permission.

409

The policy has not been migrated to Root's current ledger, so it has no ledger journal entries to invoice.

Language

Credentials

Basic

base64

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Success