# Light API documentation

> REST API for accounting documents, invoices, payments, cards and the ledger. Base URL `https://api.light.inc`. 208 endpoints across 31 resources.

Append `.md` to any page URL below for its markdown source. The whole reference in one file: https://light.inc/docs/llms-full.txt · The OpenAPI spec: https://light.inc/docs/openapi-public.json

For questions about using Light itself rather than its API, see https://light.inc/help and https://light.inc/llms.txt.

## Getting started

- [Introduction](https://light.inc/docs): Welcome to the Light API documentation.
- [Authentication](https://light.inc/docs/getting-started/authentication): Authenticate with an API key or the OAuth 2.0 authorization code flow.
- [Rate limits](https://light.inc/docs/getting-started/rate-limits): 300 requests a minute per user, 100,000 a day per organisation, and how to handle a 429.
- [Pagination, filtering and errors](https://light.inc/docs/getting-started/pagination-filtering-errors): How list endpoints page and sort, the filter grammar and its limits, what an error looks like, how to retry safely, and the conventions partial updates, custom properties and file endpoints follow.
- [Using Light from an AI client](https://light.inc/docs/getting-started/ai-clients): Light's MCP server for Claude and other AI clients: how it differs from the REST API, and what an agent reading this reference should know.

## Concepts

- [How Light records money](https://light.inc/docs/concepts/how-light-records-money): Documents, posting and the ledger: what the API's objects are, and why every transaction has two sides.
- [Reading amounts](https://light.inc/docs/concepts/reading-amounts): Minor units, debit and credit, signed and unsigned figures, and the three currencies on every ledger line.
- [Document lifecycle](https://light.inc/docs/concepts/document-lifecycle): The statuses every document moves through, which endpoints move them, and what can still change after posting.
- [Periods and locks](https://light.inc/docs/concepts/periods-and-locks): Why a posting is rejected with ACCOUNTING_PERIOD_CLOSED or ACCOUNTING_PERIOD_LOCKED, and what to do about it.
- [Choosing an endpoint](https://light.inc/docs/concepts/choosing-an-endpoint): Common jobs mapped to the calls that do them, in order, with the rule that trips people up on each.

## Examples

- [OAuth callback](https://light.inc/docs/examples/oauth-callback): Handle the OAuth 2.0 redirect and exchange the authorization code for an access token.
- [Create an invoice payable](https://light.inc/docs/examples/create-invoice-payable): End-to-end: create a vendor invoice with line items and a document, then submit it for approval.
- [Upload a receipt](https://light.inc/docs/examples/upload-receipt): Upload receipts for expenses and card transactions using presigned URLs.

## API reference

### Authorization
The OAuth 2.0 authorization flow: start it, and exchange the code for an access token.

- [Create access token](https://light.inc/docs/api-reference/authorization/create-access-token): `POST /oauth/token` — Exchanges an authorization code or refresh token for an access token
  - NOTE: Send the body as application/x-www-form-urlencoded , not JSON. Light forwards the six fields to its identity provider unchanged and returns its answer, so a rejected grant comes back with the provider's own status and body ( {"error": "invalid_grant", "error_description": "..."} ), not the {name, type, errors[]} envelope used elsewhere. Response keys are snake_case ( access_token , expires_in in seconds, token_type , refresh_token ), and refresh_token is null when the grant didn't produce one.
- [Start authorization flow](https://light.inc/docs/api-reference/authorization/start-authorization-flow): `GET /oauth/authorize` — Redirects the user to the authorization page to start the OAuth V2 authorization flow
  - NOTE: This endpoint does not return JSON. It answers 303 See Other with an empty body and a Location header pointing at Light's identity provider, so send the user's browser here rather than calling it from a server. client_id and redirect_uri are required; state is optional and echoed back unchanged on the callback. The scope is fixed by Light ( openid profile email offline_access ) and the user is always shown the login and consent screens; PKCE ( code_challenge ) is not supported and any scope you pass is ignored.

### Accounting Documents
List and query every accounting document, across all document types.

- [List accounting documents](https://light.inc/docs/api-reference/v1--accounting-documents/list-accounting-documents): `GET /v1/accounting-documents/accounting-documents` — Returns a paginated list of accounting documents
  - NOTE: Every posting-capable record in one list. documentType : AP vendor bill, AR customer invoice, BP bank payment, CC customer credit, CN vendor credit note, CT card transaction, DE accounting-release (amortisation or depreciation) entry, FX revaluation entry, JE journal entry, YC year-closing entry. status : DRAFT , APPROVAL_PENDING , APPROVED , POSTED , PARTIALLY_CLEARED and CLEARED (matched against payments or credits), ARCHIVED (a draft archived, or a posted document reversed). Drafts and archived documents are included unless filtered; default order is newest first. Read totalTransactionAmount as the document's absolute total and ignore its dcSign : the sign is derived from a type-specific sum, so a journal entry's total shows C and a customer invoice's shows D . postingDate , valuationDate and ledgerName can be filtered and sorted on but are not in the response; for those and for lines, use GET /v1/ledger-transaction-lines filtered by accDocId . The document types and statuses are explained in How Light records money (/docs/concepts/how-light-records-money) and Document lifecycle (/docs/concepts/document-lifecycle).

### Accounting Release Templates
Create and manage the templates that generate accounting releases, and archive the ones no longer in use.

- [Archive accounting release template](https://light.inc/docs/api-reference/v1--accounting-release-templates/archive-accounting-release-template): `POST /v1/accounting-release-templates/{templateId}/archive` — Archives the given accounting release template so it can no longer be assigned to new documents. Releases already generated from it are unaffected
  - NOTE: Idempotent and unconditional: archiving an archived template succeeds again. The only failure is 404 ACCOUNTING_RELEASE_TEMPLATE_NOT_FOUND .
- [List accounting release templates](https://light.inc/docs/api-reference/v1--accounting-release-templates/list-accounting-release-templates): `GET /v1/accounting-release-templates` — Returns a list of accounting release templates
  - NOTE: Archived templates are included; add filter=status:eq:ACTIVE to exclude them. Default order is newest first.
- [Create accounting release template](https://light.inc/docs/api-reference/v1--accounting-release-templates/create-accounting-release-template): `POST /v1/accounting-release-templates` — Creates a new accounting release template. The ledger accounts and type chosen here are fixed for the lifetime of the template
  - NOTE: residualAmount and reducingRate are not mutually exclusive as the description says: at least one is required for REDUCING_BALANCE ( ACCOUNTING_RELEASE_TEMPLATE_REDUCING_BALANCE_MISSING_RATE_OR_RESIDUAL ), and both may be sent and stored. REDUCING_BALANCE is allowed only for type FIXED_ASSET , AP or JE ; type: CONTRACT requires contractAccountId . reducingRate must be in [0, 1) , residualAmount above zero, initialAmountPercentage + residualAmountPercentage at most 1. None of the account ids may point at a payables or receivables control account ( ACCOUNTING_RELEASE_TEMPLATE_RECONCILABLE_ACCOUNT_NOT_ALLOWED ).
- [Get accounting release template](https://light.inc/docs/api-reference/v1--accounting-release-templates/get-accounting-release-template): `GET /v1/accounting-release-templates/{templateId}` — Returns an accounting release template by ID
  - NOTE: An unknown id, or one from another company, is 404 . Same permission as listing templates.
- [Update accounting release template](https://light.inc/docs/api-reference/v1--accounting-release-templates/update-accounting-release-template): `PATCH /v1/accounting-release-templates/{templateId}` — Updates an existing accounting release template. Only the fields present in the request body are changed. The ledger accounts and type are fixed at creation and cannot be updated. To use different ones, create a new template and archive this one.
  - NOTE: No status check: an ARCHIVED template can still be updated and stays archived. name , method and accumulatePastReleasesEnabled cannot be cleared; defaultDuration , the percentages, residualAmount , reducingRate and context follow the null -clears rule. The merged result is re-validated with the create rules.

### Attachments
Upload, list and manage the documents attached to a record.

- [List attachments](https://light.inc/docs/api-reference/v1--attachments/list-attachments): `GET /v1/attachments` — Returns a list of attachments associated with a specific resource
  - NOTE: Returns a bare JSON array, not the paginated {records, hasMore} envelope, and takes no filter , sort or limit . resourceId is required; an unknown id yields [] rather than 404 .
- [Create attachment](https://light.inc/docs/api-reference/v1--attachments/create-attachment): `POST /v1/attachments` — Creates a new attachment record
  - NOTE: Step three of the upload flow: documentKey is the key returned by POST /v1/attachments/upload-url , and the bytes must already be there — otherwise ATTACHMENT_FILE_NOT_FOUND . A resource can carry at most 10 attachments ( ATTACHMENT_NUMBER_FOR_RESOURCE_EXCEEDED ); the same documentKey or fileName twice on one resource fails with ATTACHMENT_DOCUMENT_KEY_ALREADY_EXISTS / ATTACHMENT_FILE_NAME_FOR_RESOURCE_ALREADY_EXISTS . resourceId is not validated. metadata is only read when Light emails a sales invoice or customer credit ( type: "AR" , shouldAttachToEmail ); on other resources it has no effect.
- [Generate attachment upload URL](https://light.inc/docs/api-reference/v1--attachments/generate-attachment-upload-url): `POST /v1/attachments/upload-url` — Generates a secure upload URL for attachment files
  - NOTE: Step one of three; see Files (/docs/getting-started/pagination-filtering-errors files). The URL is valid for five minutes . When you PUT the bytes to it, set Content-Type to the contentType you asked for and send every entry of the returned metadata as a request header — they are signed into the URL and the upload is rejected without them. Then register the file with POST /v1/attachments , passing the returned key as documentKey . fileName must be unique per resourceId ; reusing one fails with ATTACHMENT_FILE_NAME_FOR_RESOURCE_ALREADY_EXISTS . contentType must be one of the PDF, image ( image/ ), text or Office document types; anything else fails with UNSUPPORTED_FILE_MIME_TYPE . The key is generated by Light; you cannot choose it. There is no resourceType in this API: resourceId is the id of the record (an invoice, a purchase order, ...) and it is not checked against anything, so a typo produces an attachment nothing will ever show.
- [Delete attachment](https://light.inc/docs/api-reference/v1--attachments/delete-attachment): `DELETE /v1/attachments/{attachmentId}` — Deletes a specific attachment and its associated file
  - NOTE: The stored file is not deleted. Despite the description, this removes only the attachment record; the uploaded object stays in storage. Deleting is refused with ATTACHMENT_CANNOT_BE_DELETED_FOR_POSTED_DOCUMENT when the resource is an accounting document that has been posted. Any principal in the company may delete, not only the uploader. Success is 204 with no body.
- [Get attachment document](https://light.inc/docs/api-reference/v1--attachments/get-attachment-document): `GET /v1/attachments/{attachmentId}/document` — Returns the document file for a specific attachment
  - NOTE: Returns a 307 Temporary Redirect with an empty body, not the file. The Location is a pre-signed download URL valid for two hours that serves the file with its stored content type and a Content-Disposition: attachment header. Follow it without your Light Authorization header. Unknown id: 404 ATTACHMENT_NOT_FOUND .
- [Get attachment options](https://light.inc/docs/api-reference/v1--attachments/get-attachment-options): `OPTIONS /v1/attachments/{attachmentId}/document` — Handles CORS preflight requests for attachment document access
  - NOTE: CORS preflight for browsers that download the file directly. Answers 200 with the allowed-origin headers and no body, without authentication. API clients never need to call it.

### Bank Accounts
Create and access bank accounts. Creating one also creates its linked ledger account atomically.

- [Get bank accounts of the company](https://light.inc/docs/api-reference/v1--bank-accounts/get-bank-accounts-of-the-company): `GET /v1/bank-accounts` — Returns all bank accounts of the company
  - NOTE: Not paginated and not filterable: every bank account of the company, with no status to tell active from retired ones.
- [Create bank account](https://light.inc/docs/api-reference/v1--bank-accounts/create-bank-account): `POST /v1/bank-accounts` — Creates a bank account along with its linked ledger (chart-of-accounts) entry in a single transaction. The ledger account code must be a unique 6-digit integer within the company's chart of accounts.
  - NOTE: The ledger account is created with fixed attributes you cannot choose: type BANK , active, revalued for FX at end-of-month rates, in the bank account's currency, scoped to the one companyEntityId . Its label defaults to the bank account's name , not the bank name as the description says. code must be exactly six digits ( LEDGER_ACCOUNT_CODE_LENGTH ) and unused ( BANK_ACCOUNT_LEDGER_ACCOUNT_CODE_ALREADY_EXISTS ; nothing is created). bankProvider: OTHER requires bankName ; other providers fill it in. The response's type and paymentSchedulingEligibility are derived from the provider (only Airwallex accounts are VIRTUAL ; only providers Light can pay through are INTERNAL , everything else INELIGIBLE ). Company-admin role only.
- [List bank transactions](https://light.inc/docs/api-reference/v1--bank-accounts/list-bank-transactions): `GET /v1/bank-accounts/{bankAccountId}/bank-transactions` — Returns a paginated list of bank transactions for the specified bank account, including the balance
  - NOTE: balance is not the page's balance: it is D minus C over every transaction matching the filter, and, unlike GET .../balance , it includes EXCLUDED transactions unless you filter them out. Cursor pagination doesn't apply here: cursor is treated as an offset and the response has no nextCursor or hasMore , so page with offset , limit and total . Default order is newest-created first, not by date .
- [Create bank transactions](https://light.inc/docs/api-reference/v1--bank-accounts/create-bank-transactions): `POST /v1/bank-accounts/{bankAccountId}/bank-transactions` — Creates bank transactions in batch. Maximum 500 transactions per request. Duplicate transactions (same transactionId for the same bank account) are silently skipped.
  - NOTE: dcSign is the reverse of the description. A bank account is an asset, so D is money in (increases the balance) and C is money out ; this is what the bank feeds, the CSV import and both balance endpoints use. Sending D for outflows inverts every balance. Duplicate handling is silent: a row whose transactionId already exists for this API on the account is skipped and simply missing from the response (a full retry returns [] ). Rows with transactionId: null are never de-duplicated, and a transaction already present from a bank feed or CSV import under the same id is not treated as a duplicate either. Over 500 rows is BANK_TRANSACTION_BATCH_SIZE_EXCEEDED , an empty list BANK_TRANSACTION_BATCH_EMPTY . Nothing is posted to the ledger: transactions land as UNMATCHED for bank reconciliation only. A negative amount is accepted and flips the arithmetic, so keep amounts positive and use dcSign .
- [List bank account activity events](https://light.inc/docs/api-reference/v1--bank-accounts/list-bank-account-activity-events): `GET /v1/bank-accounts/{bankAccountId}/activity-events` — The bank account's activity timeline, newest first: who did what to it, when, and which fields changed. Requires permission to view this bank account. The entityId and entityType filters are fixed by the path here; passing them can only narrow the result.
- [Get bank account balance](https://light.inc/docs/api-reference/v1--bank-accounts/get-bank-account-balance): `GET /v1/bank-accounts/{bankAccountId}/balance` — Returns the bank statement balance and ledger balance for a bank account as of the given date. If asOf is omitted, today's balance is returned. The bank balance is derived from the opening balance plus all bank transactions on or before asOf ; the ledger balance is the sum of ledger transaction lines posted on or before asOf for the linked ledger account.
  - NOTE: bankBalance is the stored closing balance plus the signed non-EXCLUDED transactions dated after its day up to asOf ; it is null when no balance has been set or when asOf is before the day the balance was set for . ledgerBalance is the debit-positive sum, in the transaction currency, of lines on the linked ledger account posted up to asOf , excluding FX revaluations, archived documents and reversed lines; it is 0 rather than null when there are none.
- [Upsert bank account balance](https://light.inc/docs/api-reference/v1--bank-accounts/upsert-bank-account-balance): `PUT /v1/bank-accounts/{bankAccountId}/balance` — Creates or updates the opening balance for a bank account. Only one balance per bank account is allowed — subsequent calls update the existing balance.
  - NOTE: This stores a closing (end-of-day) balance, not an opening one. balanceAt is normalised to 23:59:59 UTC of its day, and transactions dated on or before that day are treated as already included in the balance; only later transactions are added on top. So give the statement balance at the end of that day, and load transactions dated after it. A second call replaces both balance and balanceAt for the account.
- [Get bank transaction](https://light.inc/docs/api-reference/v1--bank-accounts/get-bank-transaction): `GET /v1/bank-accounts/{bankAccountId}/bank-transactions/{bankTransactionId}` — Returns a specific bank transaction by ID
  - NOTE: 404 unless the transaction belongs to that bank account.

### Invoice Payables
Create, approve, decline and mark as paid — bills and their line items, end to end.

- [List invoice payables](https://light.inc/docs/api-reference/v1--invoice-payables/list-invoice-payables): `GET /v1/bff/invoice-payables` — Returns a paginated list of invoice payables
  - NOTE: This is the only list operation for invoice payables — /v1/invoice-payables has no GET . The single-record read is GET /v1/invoice-payables/{invoicePayableId} , and it returns a different shape : list rows have no lineItems , customProperties , outstandingBalance , purchaseOrderId , FX rates or payment references, and instead carry vendor , user , nextApprover , companyEntityName and documentKey . nextApprover is null when the next approver is a user group. include accepts only REIMBURSEMENT . The documentNumber filter matches the invoice number. A credential without the company-admin, AP-preparation or auditor role must filter on its own user id ( approverUserId:eq:<id for an approver, userId:eq:<id for reimbursements) or it receives 403 . No searchTerm .
- [Approve invoice payable](https://light.inc/docs/api-reference/v1--invoice-payables/approve-invoice-payable): `POST /v1/invoice-payables/{invoicePayableId}/approve` — Approves an invoice payable for payment processing
  - NOTE: Records the decision of the credential's user , who must be one of the bill's assigned approvers ( USER_NOT_PART_OF_APPROVAL ) with the invoice-approver role; an API key approves as its service account, so it must have been assigned by the workflow. With several approvers the state stays APPROVAL_PENDING until the last one approves, then moves to APPROVED_ACCOUNTING_ENTRY_PENDING and is posted in the background, ending in READY_FOR_PAYMENT_RELEASE , SCHEDULED or UNPAID . If the bill's approval is no longer in progress the call is a silent no-op returning the bill; a bill with no approval at all is 404 INVOICE_APPROVAL_NOT_FOUND .
- [Cancel invoice payable](https://light.inc/docs/api-reference/v1--invoice-payables/cancel-invoice-payable): `POST /v1/invoice-payables/{invoicePayableId}/cancel` — Cancels an invoice payable
  - NOTE: From IN_DRAFT , DUPLICATED , DECLINED or APPROVAL_PENDING the bill is cancelled immediately. From a posted, unpaid state ( UNPAID , READY_FOR_PAYMENT_RELEASE , SCHEDULED , PAYMENT_PAUSED , PENDING_PAYMENT_APPROVAL , PAYMENT_PENDING ) it moves to CANCELLATION_PENDING and becomes CANCELLED once the ledger entry is reversed in the background; this needs an open accounting period. PAID , PARTIALLY_PAID and COMPLETED cannot be cancelled: reverse the clearings first. Cancelling a cancelled bill is a no-op. The body is optional; reason is stored as cancellationReason .
- [Create invoice payable](https://light.inc/docs/api-reference/v1--invoice-payables/create-invoice-payable): `POST /v1/invoice-payables` — Creates a new invoice payable document. Supports inline line items via the lineItems field for single-request creation.
  - NOTE: processingMode decides which fields are read. With AI_PARSE_AND_MERGE only vendorId , amount and currency are used; companyEntityId , invoiceNumber , dates, senderBankAccountId , lineItems , customProperties and FX overrides are silently dropped , and the invoice is created in CREATED , where it waits for a document: upload one via POST .../document/upload-url , after which AI parsing fills the fields and moves it to IN_DRAFT in the background. With DATA_ONLY every field is stored, the invoice starts in IN_DRAFT , and a later document upload only attaches the file. There is no GET on this path; list with GET /v1/bff/invoice-payables . Line items: with lineItemsIncludeTax: true send amount (gross) and omit netAmount ; with false send netAmount and omit amount — the wrong field or both fails with INVALID_LINE_ITEM_AMOUNT_TYPE . Lines don't have to add up to amount yet; that is checked at submit or post ( INVALID_LINE_ITEM_SUM ). When companyEntityId is set, line tax amounts are recomputed from taxCodeId . Payee fields are copied from the vendor and cannot be set. senderBankAccountId omitted with an entity given defaults to the entity's bank account for the currency. type is always VENDOR_INVOICE . outstandingBalance is null on every response except a GET with includeOutstandingBalance=true .
- [Generate document upload URL](https://light.inc/docs/api-reference/v1--invoice-payables/generate-document-upload-url): `POST /v1/invoice-payables/{invoicePayableId}/document/upload-url` — Generates a secure upload URL for invoice payable documents
  - NOTE: The URL is valid for five minutes. PUT the bytes to it with every returned header set on the request — they carry the signed metadata that ties the file to the bill (see Files (/docs/getting-started/pagination-filtering-errors files)). Nothing else to call: Light attaches the file in the background, so poll GET /v1/invoice-payables/{invoicePayableId} until documentName is set. What happens next depends on state: a bill in CREATED (created with AI_PARSE_AND_MERGE ) is parsed and moves to IN_DRAFT ; a bill already in IN_DRAFT just gets the file, with nothing parsed or overwritten. A document is required before submit-for-approval and before converting to a credit note.
- [Create invoice payable line item](https://light.inc/docs/api-reference/v1--invoice-payables/create-invoice-payable-line-item): `POST /v1/invoice-payables/{invoicePayableId}/line-items` — Creates an invoice payable line item
  - NOTE: Only while the bill is IN_DRAFT ( INVALID_LINE_ITEM_INVOICE_PAYABLE_STATE ). Send amount or netAmount according to the bill's lineItemsIncludeTax , never both ( INVALID_LINE_ITEM_AMOUNT_TYPE ). accountId may not be a payables or receivables control account ( DISALLOWED_LINE_ITEM_ACCOUNT_TYPE ). When the bill has an entity, taxAmount is recomputed from the tax code. costCenterId cannot be set through the API.
- [Decline invoice payable](https://light.inc/docs/api-reference/v1--invoice-payables/decline-invoice-payable): `POST /v1/invoice-payables/{invoicePayableId}/decline` — Declines an invoice payable
  - NOTE: Records the decision of the credential's user, who must be an assigned approver ( USER_NOT_PART_OF_APPROVAL ). The bill moves to DECLINED , from which the only public action is cancel ; there is no reset. If the approval is no longer in progress the call is a silent no-op.
- [Get invoice payable line item](https://light.inc/docs/api-reference/v1--invoice-payables/get-invoice-payable-line-item): `GET /v1/invoice-payables/{invoicePayableId}/line-items/{lineItemId}` — Gets an invoice payable line item
  - NOTE: Requires the permission to update bills, not only to view them; a read-only key gets 403 .
- [Update invoice payable line item](https://light.inc/docs/api-reference/v1--invoice-payables/update-invoice-payable-line-item): `PUT /v1/invoice-payables/{invoicePayableId}/line-items/{lineItemId}` — Updates an invoice payable line item
  - NOTE: Only while the bill is IN_DRAFT ( INVALID_LINE_ITEM_INVOICE_PAYABLE_STATE ). Not a strict replace: an omitted taxCodeId or accountId keeps the current value, and taxAmount is recomputed whenever the amount changes. amount versus netAmount follows the bill's lineItemsIncludeTax ( INVALID_LINE_ITEM_AMOUNT_TYPE ). metadata.type defaults to VENDOR_INVOICE and must match the bill's type .
- [Delete invoice payable line item](https://light.inc/docs/api-reference/v1--invoice-payables/delete-invoice-payable-line-item): `DELETE /v1/invoice-payables/{invoicePayableId}/line-items/{lineItemId}` — Deletes an invoice payable line item
  - NOTE: Only while the bill is IN_DRAFT ( INVALID_LINE_ITEM_INVOICE_PAYABLE_STATE ). Answers 204 with no body.
- [Get invoice payable](https://light.inc/docs/api-reference/v1--invoice-payables/get-invoice-payable): `GET /v1/invoice-payables/{invoicePayableId}` — Returns a specific invoice payable by ID
  - NOTE: To list payables, use GET /v1/bff/invoice-payables — this path has no list operation, and the list returns a slimmer shape. outstandingBalance is populated only with includeOutstandingBalance=true and a positive amount ; it is null if the computed balance would be negative. purchaseOrderId reflects the purchase order matched to the bill in Light, which no public endpoint sets. States and the endpoint that moves them: CREATED (waiting for a document) → IN_DRAFT (parsing done, or created with DATA_ONLY ) → APPROVAL_REQUESTED → APPROVAL_PENDING (via submit-for-approval ) → APPROVED_ACCOUNTING_ENTRY_PENDING (last approve ) → READY_FOR_PAYMENT_RELEASE , SCHEDULED or UNPAID depending on how the bill will be paid; or IN_DRAFT → UNPAID via post . mark-as-paid gives PAID (then COMPLETED once settled) or PARTIALLY_PAID . Also DUPLICATED , DECLINED , CANCELLATION_PENDING , CANCELLED , PAYMENT_PAUSED , PENDING_PAYMENT_APPROVAL , PAYMENT_PENDING . Every _PENDING state resolves in the background, so poll this endpoint. Any action called in the wrong state fails with INVOICE_PAYABLE_EVENT_NOT_SUPPORTED .
- [Update invoice payable](https://light.inc/docs/api-reference/v1--invoice-payables/update-invoice-payable): `PATCH /v1/invoice-payables/{invoicePayableId}` — Updates an existing invoice payable document header
  - NOTE: Only in IN_DRAFT or DUPLICATED ( INVOICE_PAYABLE_EVENT_NOT_SUPPORTED otherwise); for a posted bill only PATCH .../custom-properties works. purchaseOrderId is accepted and ignored : the field in responses comes from Light's bill-to-order matching, which has no public endpoint. Most fields follow the omit-to-keep, null -to-clear rule; lineItemsIncludeTax and customProperties cannot be cleared. Every update runs duplicate detection: if another live bill has the same invoiceNumber and vendorId , the call still returns 200 but with state: DUPLICATED , failureReason: DUPLICATE_INVOICE and the other bill's id in failureContext — patch again or cancel. Changing vendorId re-copies the payee fields, defaults companyEntityId to the vendor's entity, and rewrites line account, tax and cost centre from the vendor's defaults; changing companyEntityId clears account and tax code on every line, and the entity must be one the vendor is enabled for ( INVOICE_PAYABLE_COMPANY_ENTITY_NOT_ALLOWED_FOR_VENDOR ). invoiceNumber and the payment references have all whitespace removed.
- [List bill activity events](https://light.inc/docs/api-reference/v1--invoice-payables/list-bill-activity-events): `GET /v1/invoice-payables/{invoicePayableId}/activity-events` — The bill's activity timeline, newest first: who did what to it, when, and which fields changed. Requires permission to view this bill. The entityId and entityType filters are fixed by the path here; passing them can only narrow the result.
- [Get invoice document](https://light.inc/docs/api-reference/v1--invoice-payables/get-invoice-document): `GET /v1/invoice-payables/{invoicePayableId}/document` — Returns the attached document for an invoice payable
  - NOTE: Answers 307 Temporary Redirect to a pre-signed download URL valid for 30 minutes, not the file; follow it without your Light Authorization header. documentType=GENERATED returns the PDF Light renders at submission, which exists only after submit-for-approval ( 404 INVOICE_PAYABLE_DOCUMENT_TYPE_NOT_FOUND before that); the default ORIGINAL is the uploaded file.
- [Get linked credit notes](https://light.inc/docs/api-reference/v1--invoice-payables/get-linked-credit-notes): `GET /v1/invoice-payables/{invoicePayableId}/credit-notes` — Returns all credit notes linked to the invoice payable
  - NOTE: Not paginated: every linked credit note comes back in one list.
- [List invoice payable payments](https://light.inc/docs/api-reference/v1--invoice-payables/list-invoice-payable-payments): `GET /v1/invoice-payables/{invoicePayableId}/payments` — Returns all clearings (bank payments and credit notes) linked to the invoice payable. Each entry carries a type discriminator ( BP for bank payments, CN for credit notes) so consumers can filter client-side if only one kind is needed. Reversed clearings are excluded.
  - NOTE: A plain array. The top-level id is the clearing event, not the document: to reverse a payment, pass payment.accountingDocumentId and the matching type ( BP or CN ) to reverse-clearing . amount is the cleared amount in the invoice currency. payment is null for clearing types the API doesn't model.
- [Mark invoice payable as paid](https://light.inc/docs/api-reference/v1--invoice-payables/mark-invoice-payable-as-paid): `POST /v1/invoice-payables/{invoicePayableId}/mark-as-paid` — Marks an invoice payable as paid by recording a bank payment that clears it. Use paymentOption=FULL to clear the remaining outstanding balance, or paymentOption=PARTIAL to record an installment. The invoice transitions to PAID (full) or PARTIALLY_PAID (partial).
  - NOTE: paymentAt is required , contrary to the description; omitting it fails with INVOICE_PAYABLE_MARK_AS_PAID_INVALID_FIELD ("Payment date is required"). One of bankAccountId or ledgerAccountId is also required. amount is in the bank account's currency when you pay from a bank account (the invoice amount is converted at the company rate), and in the invoice currency for a non-bank ledger account. Allowed from UNPAID , READY_FOR_PAYMENT_RELEASE , SCHEDULED , PAYMENT_PENDING and PARTIALLY_PAID . paymentOption: FULL needs amount at least the remaining balance ( INVOICE_PAYABLE_FULL_PAYMENT_AMOUNT_TOO_SMALL ); any excess is booked as bank fees and the bill becomes PAID , then COMPLETED once settled. PARTIAL needs amount below the balance ( INVOICE_PAYABLE_PARTIAL_PAYMENT_AMOUNT_TOO_LARGE ) and gives PARTIALLY_PAID without storing paymentAt . Either way a bank-payment document is posted that clears the bill; it appears on GET .../payments as type BP , and its payment.accountingDocumentId is what reverse-clearing takes. Requires a user credential.
- [Post invoice payable without approval](https://light.inc/docs/api-reference/v1--invoice-payables/post-invoice-payable-without-approval): `POST /v1/invoice-payables/{invoicePayableId}/post` — Posts an invoice payable directly to the ledger without going through the approval workflow. The invoice must be in IN_DRAFT state. After posting, linked credit notes are applied and unlinked credit notes may be auto-allocated. If the invoice is fully cleared by credit notes, it transitions to COMPLETED ; otherwise it transitions to UNPAID .
  - NOTE: The shortcut past approval: from IN_DRAFT straight to the ledger, synchronously, landing in UNPAID (or COMPLETED if nothing is owed). Any other state fails with INVOICE_PAYABLE_EVENT_NOT_SUPPORTED . Requires the company-admin role and a company using Light's ledger ( LEDGER_NOT_ENABLED_FOR_COMPANY otherwise). Compare approve , which records one approver's decision on a bill in APPROVAL_PENDING and posts in the background once the last approver has approved.
- [Reverse invoice payable payment](https://light.inc/docs/api-reference/v1--invoice-payables/reverse-invoice-payable-payment): `POST /v1/invoice-payables/{invoicePayableId}/reverse-clearing` — Reverses a clearing applied to an invoice payable — either a bank payment ( BP ) or a credit note ( CN ) — identified by its accounting document ID. Use the List invoice payable payments endpoint to obtain the accountingDocumentId and type of the clearing to reverse. Reversing removes the clearing's effect from the ledger and transitions the invoice back to UNPAID or PARTIALLY_PAID depending on the remaining outstanding balance. Optionally set shouldArchiveClearingDocument to also archive the underlying bank payment or credit note.
  - NOTE: Only from PARTIALLY_PAID or COMPLETED . A bill in PAID (marked as paid but not yet settled) is not accepted until it reaches COMPLETED ; anything else fails with INVOICE_PAYABLE_EVENT_NOT_SUPPORTED . clearingAccountingDocumentId is the payment.accountingDocumentId from GET .../payments . The result mirrors the ledger: PARTIALLY_PAID if anything is still cleared, otherwise UNPAID . Reversing a credit-note clearing also removes the link; shouldArchiveClearingDocument archives the payment or credit note as well.
- [Submit for approval](https://light.inc/docs/api-reference/v1--invoice-payables/submit-for-approval): `POST /v1/invoice-payables/{invoicePayableId}/submit-for-approval` — Submits an invoice for approval
  - NOTE: Only from IN_DRAFT , and validated synchronously: a document ( documentKey ), amount above zero, currency , paymentAt , issuedDate , dueDate , companyEntityId , senderBankAccountId , invoiceNumber , vendorId ( INVOICE_PAYABLE_MISSING_FIELD names the field); at least one line, each with amount , accountId , taxCodeId and taxAmount ( INVOICE_PAYABLE_LINE_MISSING_FIELD ); lines summing to amount ( INVALID_LINE_ITEM_SUM ); payee name and countries copied from the vendor ( INVOICE_PAYABLE_MISSING_PAYEE_FIELD ); required custom properties; and a ledger posting preview, so a closed accounting period fails here. The body is optional. Approvers cannot be set through the API: they come from the company's bill-approval workflow. The response is APPROVAL_REQUESTED ; the approval records are created in the background, after which the state is APPROVAL_PENDING — or back to IN_DRAFT with failureReason: APPROVAL_SUBMISSION_FAILED when, for example, no approver could be assigned. closePurchaseOrder closes the order matched to the bill in Light, not any purchaseOrderId you sent. Requires the AP-clerk role.
- [Update the custom properties of a posted invoice payable](https://light.inc/docs/api-reference/v1--invoice-payables/update-the-custom-properties-of-a-posted-invoice-payable): `PATCH /v1/invoice-payables/{invoicePayableId}/custom-properties` — Replaces all custom fields on an invoice payable after it has been posted/approved (e.g. ready for payment release, scheduled, unpaid, partially paid, completed). Any custom property group not included in the request is removed. Use this to set fields such as a reconciliation link once the invoice has left the inbox. Editing is locked while approval is actively pending.
  - NOTE: For posted bills only: READY_FOR_PAYMENT_RELEASE , SCHEDULED , PAYMENT_PAUSED , PENDING_PAYMENT_APPROVAL , UNPAID , PARTIALLY_PAID and COMPLETED . In IN_DRAFT use the header PATCH ; in APPROVAL_PENDING , PAID , DECLINED and CANCELLED it fails with INVOICE_PAYABLE_EVENT_NOT_SUPPORTED . One more trap: an UNPAID bill whose sender bank account is eligible for payment scheduling rejects every call with INVOICE_PAYABLE_MODIFY_POSTED_FIELD_NOT_ALLOWED . The list replaces all custom properties.

### Card Balance Accounts
Access card balance accounts, their statements and total spend.

- [Generate a card balance account statement](https://light.inc/docs/api-reference/v1--card-balance-accounts/generate-a-card-balance-account-statement): `GET /v1/card-balance-accounts/{accountId}/statement` — Generates a statement for a card balance account over a period. Dates are interpreted as UTC day boundaries and all timestamps in the response are in UTC. Runs a fresh provider sync inline so the statement reflects the latest activity.
  - NOTE: A JSON statement, not a PDF, built from the issuer's own ledger for the balance account rather than from Light card transactions (Light syncs with the issuer before answering). to is exclusive (start of that UTC day) and must be after from ( CARD_BALANCE_ACCOUNT_STATEMENT_INVALID_PERIOD ). openingBalance is the booked balance before from ; runningBalance adds credits and subtracts debits from there. Line amounts are unsigned with the sign in direction . Company-admin and auditor roles only, and at most two concurrent calls per credential ( 429 beyond that).
- [Get card balance account](https://light.inc/docs/api-reference/v1--card-balance-accounts/get-card-balance-account): `GET /v1/card-balance-accounts/{accountId}` — Returns a card balance account by ID, including balance details
  - NOTE: balance is read live from the card issuer; if the issuer cannot answer, it comes back as zeros rather than an error.
- [List card balance accounts](https://light.inc/docs/api-reference/v1--card-balance-accounts/list-card-balance-accounts): `GET /v1/card-balance-accounts` — Returns a list of card balance accounts
  - NOTE: balance is read live from the card issuer for every account on each call; if the issuer cannot answer for an account, its balance comes back as zeros rather than an error.
- [Get total spend for a card balance account](https://light.inc/docs/api-reference/v1--card-balance-accounts/get-total-spend-for-a-card-balance-account): `GET /v1/card-balance-accounts/{accountId}/total-spend` — Returns the total spend for a card balance account within a date range
  - NOTE: to is exclusive , contrary to the description: it is taken as the start of that UTC day, so to=2026-01-31 excludes 31 January. Omit to to count up to now. from is inclusive from 00:00 UTC. The total counts transactions in AUTHORIZED , CAPTURED , POSTED and REFUNDED , adding DEBIT amounts and subtracting CREDIT ones, so refunds reduce it and it can be negative. DECLINED and VOIDED are ignored. The response echoes from and to as the resolved instants.

### Card Customers
Retrieve the card integration public key.

- [Get card integration public key](https://light.inc/docs/api-reference/v1--card-customers/get-card-integration-public-key): `GET /v1/card-customers/public-key` — Returns the public key for the cards integration service
  - NOTE: The issuer's RSA public key for card-detail reveal: a client encrypts its session key with it when displaying a card's number and CVC. The reveal call itself is not part of this API, so most integrations never need this endpoint. companyEntityId must be an entity set up for cards ( CARD_CUSTOMER_NOT_RECOGNIZED ).

### Card Transactions
List, post and update card transactions and their receipts.

- [Batch update card transactions](https://light.inc/docs/api-reference/v1--card-transactions/batch-update-card-transactions): `PATCH /v1/card-transactions/batch-update` — Updates multiple card transactions in a single operation
  - NOTE: Asynchronous. The call authorises every id up front (one id you may not update makes the whole request 403 ), queues the work and returns an empty body immediately; nothing in the response tells you whether any update succeeded. Items are processed independently: one failing item does not stop the others, and a failure that is a validation error is written to that transaction's failureContext , where a later GET shows it. Poll updatedAt or failureContext on the transactions to confirm. There is no cap on the list length. This is the only endpoint that accepts postingDate , and it is write-only from the card side: no card-transaction response returns it. Read it back on the ledger line ( GET /v1/ledger-transaction-lines , postingDate ) once the transaction is posted. Line updates here take description , accountId , taxCodeId and customProperties only; edits to a posted transaction fail into failureContext rather than being rejected up front.
- [Generate receipt upload URL](https://light.inc/docs/api-reference/v1--card-transactions/generate-receipt-upload-url): `POST /v1/card-transactions/{cardTransactionId}/receipt-upload-url` — Generates a secure upload URL for receipt documents
  - NOTE: The URL is valid for five minutes ; PUT the bytes with the declared Content-Type and every entry of metadata as a request header , or the upload is rejected (see Files (/docs/getting-started/pagination-filtering-errors files)). There is no follow-up call: Light picks the file up, converts it to PDF and sets receiptDocumentKey asynchronously — to the key of the converted PDF , not the key returned here — so poll GET /v1/card-transactions/{id} until it is non-null. If conversion fails, failureContext is set with CARD_TRANSACTION_PDF_RECEIPT_FAILED . While the transaction is unposted the receipt is also read by Light's document AI, which writes the account, tax code and custom properties it extracts onto every line — coding you set before the upload can be overwritten. The cardTransactionId is not checked at this step; a wrong id only fails later, inside the background job. Requires a user credential, not an API key.
- [Get card transaction](https://light.inc/docs/api-reference/v1--card-transactions/get-card-transaction): `GET /v1/card-transactions/{cardTransactionId}` — Returns a card transaction by ID
  - NOTE: Returns the same enriched shape as the list, without editStatus . To learn whether a transaction is still editable, read status ( POSTED , DECLINED and VOIDED are locked; AUTHORIZED allows everything but line amounts) or look at the editStatus on a PATCH response.
- [List card transaction activity events](https://light.inc/docs/api-reference/v1--card-transactions/list-card-transaction-activity-events): `GET /v1/card-transactions/{cardTransactionId}/activity-events` — The card transaction's activity timeline, newest first: who did what to it, when, and which fields changed. Requires permission to view this card transaction. The entityId and entityType filters are fixed by the path here; passing them can only narrow the result.
- [Get transaction receipt](https://light.inc/docs/api-reference/v1--card-transactions/get-transaction-receipt): `GET /v1/card-transactions/{transactionId}/receipt` — Returns the attached receipt document for a card transaction
  - NOTE: Answers 307 Temporary Redirect to a pre-signed download URL valid for two hours, not the PDF bytes; follow it without your Light Authorization header. A transaction without a receipt fails with CARD_TRANSACTION_MISSING_RECEIPT .
- [Remove transaction receipt](https://light.inc/docs/api-reference/v1--card-transactions/remove-transaction-receipt): `DELETE /v1/card-transactions/{transactionId}/receipt` — Removes the attached receipt document from a card transaction
  - NOTE: Clears receiptDocumentKey on the transaction; the stored file itself is kept. Works in any status and answers with an empty body.
- [OPTIONS /v1/card-transactions/{transactionId}/receipt](https://light.inc/docs/api-reference/v1--card-transactions/get-card-transaction-receipt-options): `OPTIONS /v1/card-transactions/{transactionId}/receipt`
  - NOTE: CORS preflight for browsers that download the receipt directly. Answers 200 with the allowed-origin headers and no body, without authentication. API clients never need to call it.
- [List card transactions](https://light.inc/docs/api-reference/v1--card-transactions/list-card-transactions): `GET /v1/card-transactions` — Returns a paginated list of card transactions
  - NOTE: The filter and sort field lists below are incomplete. The server also accepts ownerId , amount , originalAmount , originalCurrency , receiptDocumentKey , taxId and accountId as filters and originalAmount as a sort; an unknown field fails with INVALID_QUERY_FIELD listing the real set. The two undocumented flags: onlyPostable=true returns transactions a post would currently succeed for (a flag recomputed in the background after each edit, so it can lag a moment behind a PATCH ); missingData=true returns transactions with no receipt, or not yet posted and not postable. Sending both fails with CARD_TRANSACTION_INVALID_FILTER_COMBINATION . This list (and the single GET ) returns the enriched shape with labels and exportedAt , but without editStatus — that field only appears on the PATCH , post and reset responses. amount is an unsigned magnitude; direction ( DEBIT for spend, CREDIT for a refund or incoming credit) carries the sign. A refund is a separate transaction with status: REFUNDED , not a change to the original capture, and nothing on the model links the two. If the company's card setup has auto-posting on, a transaction can already be POSTED the first time you see it. A cardholder-only credential must filter on its own ownerId or cardId or it receives 403 .
- [Import card transactions](https://light.inc/docs/api-reference/v1--card-transactions/import-card-transactions): `POST /v1/card-transactions/import` — Imports a batch of up to 100 external card transactions. Each row is validated and created independently, so one bad row does not affect the others -- the response has one result per row, in the same order as the request. Larger batches are rejected as a whole. 'providerId' is the row's idempotency key: a row whose providerId was already imported comes back as SKIPPED_DUPLICATE with the existing transaction id. Always pass the issuer's own transaction id when you have one; when omitted, the key is derived from the row's card, amount, date and merchant, so re-sending the same rows is safe but two genuinely different transactions with identical content in one request are kept apart only by their order. 'amount' and 'currency' are what settled on the card's balance account and must be in that account's currency; for a purchase made in another currency, pass the purchase-side amount as 'originalAmount' and 'originalCurrency'. Rules, each failing only that row: both or neither; the same currency must carry the same amount; both amounts are positive magnitudes and 'direction' carries the sign. When omitted they default to the settled amount.
- [Post card transaction](https://light.inc/docs/api-reference/v1--card-transactions/post-card-transaction): `POST /v1/card-transactions/{transactionId}/post` — Posts a card transaction to the ledger
  - NOTE: Requires status CAPTURED or REFUNDED ( CARD_TRANSACTION_CANNOT_BE_POSTED otherwise), a ledger account and a tax code on every line, and every required custom property. Posting writes the lines to the ledger plus an offsetting entry on the ledger account that represents the card balance account; when the transaction currency differs from the entity's, an exchange rate for the posting date must exist. Afterwards status is POSTED and editStatus ALL_EDITS_LOCKED ; use reset to edit again. Company-admin or AP-clerk roles only; cardholders cannot post.
- [Reset card transaction](https://light.inc/docs/api-reference/v1--card-transactions/reset-card-transaction): `POST /v1/card-transactions/{transactionId}/reset` — Reverses a posted card transaction's ledger entries and returns it to an editable state
  - NOTE: Only a POSTED transaction can be reset; anything else fails with CARD_TRANSACTION_CANNOT_BE_RESET . The ledger entries are reversed and status returns to CAPTURED (for a DEBIT ) or REFUNDED (for a CREDIT ), with editStatus back to ALL_EDITS_ALLOWED .
- [Update card transaction](https://light.inc/docs/api-reference/v1--card-transactions/update-card-transaction): `PATCH /v1/card-transactions/{transactionId}` — Updates an existing card transaction
  - NOTE: Only description and customProperties are applied. postingDate is not accepted here — the batch endpoint is the only place it can be set. description follows the usual rule (omit to keep, null to clear). Required custom properties are enforced when the transaction is posted, not here. The response is the base shape, which includes editStatus .
- [Update card transaction line](https://light.inc/docs/api-reference/v1--card-transactions/update-card-transaction-line): `PATCH /v1/card-transactions/{transactionId}/lines/{transactionLineId}` — Updates a specific card transaction line item
  - NOTE: Rejected with CARD_TRANSACTION_NOT_EDITABLE once the transaction is POSTED , DECLINED or VOIDED . While it is still AUTHORIZED , every field except amount may change; sending a different amount fails with CARD_TRANSACTION_AMOUNT_NOT_EDITABLE until the capture arrives. amount is the gross line amount in minor units of the balance account's currency, unsigned. All fields follow the omit-to-keep, null -to-clear rule. There is no endpoint to add or remove lines.

### Cards
Create, freeze, unfreeze and manage corporate cards.

- [List cards](https://light.inc/docs/api-reference/v1--cards/list-cards): `GET /v1/cards` — Returns a paginated list of cards
  - NOTE: The filter and sort field lists below are incomplete. The server also accepts ownerId , companyEntityId , formFactor and lastFour as filters and companyEntityId , cardBalanceAccountId , formFactor , type and lastFour as sorts. A cardholder-only credential must filter ownerId:eq:<its own user id or it receives 403 . status is one of ACTIVE , FROZEN , CLOSED or the transient UPDATE_IN_PROGRESS .
- [Create card](https://light.inc/docs/api-reference/v1--cards/create-card): `POST /v1/cards` — Creates a new card. Use metadata type 'VENDOR' for vendor cards or 'EMPLOYEE' for employee cards.
  - NOTE: Creation is synchronous with the card issuer: the response is the finished card, and a virtual card comes back ACTIVE and ready to use. A physical card is activated by POST /v1/cards/{cardId}/unfreeze once the cardholder has it. Preconditions, all 400 : the balance account is active ( CARD_BALANCE_ACCOUNT_NOT_ACTIVE ), its entity is set up for cards ( COMPANY_ENTITY_NOT_ACTIVE_ON_CARDS ), and ownerId is an active user ( CARD_CREATION_OWNER_NOT_RECOGNIZED ). With metadata.type = VENDOR the vendor must exist and be linked to that entity ( CARD_CREATION_VENDOR_NOT_RECOGNIZED ); with EMPLOYEE nothing further is validated. Two limits with the same interval fail with CARD_CREATION_CONFLICTING_LIMITS . formFactor defaults to VIRTUAL . Send an X-Idempotency-Key header: a retry with the same key returns the existing card, while a retry without one issues a second card. threeDs.password is generated by Light and always returned masked as . Not available in the sandbox.
- [Freeze card](https://light.inc/docs/api-reference/v1--cards/freeze-card): `POST /v1/cards/{cardId}/freeze` — Freezes a card to block transactions
  - NOTE: While the issuer is updated the card reads UPDATE_IN_PROGRESS ; a second call during that window fails with CARD_UPDATE_IN_PROGRESS , and a CLOSED card with CARD_CLOSED . Freezing a card that is already frozen succeeds without change. Deactivating a user with PUT /v1/users/{userId}/status freezes every card they own.
- [Get card](https://light.inc/docs/api-reference/v1--cards/get-card): `GET /v1/cards/{cardId}` — Returns a card by ID
  - NOTE: Company admins, AP clerks and auditors can read any card; a cardholder only their own ( 403 otherwise).
- [List card activity events](https://light.inc/docs/api-reference/v1--cards/list-card-activity-events): `GET /v1/cards/{cardId}/activity-events` — The card's activity timeline, newest first: who did what to it, when, and which fields changed. Requires permission to view this card. The entityId and entityType filters are fixed by the path here; passing them can only narrow the result.
- [Unfreeze card](https://light.inc/docs/api-reference/v1--cards/unfreeze-card): `POST /v1/cards/{cardId}/unfreeze` — Unfreezes a card to allow transactions. For physical cards, this confirms the cardholder is in possession of the card.
  - NOTE: Same transient UPDATE_IN_PROGRESS state and errors as freeze ( CARD_UPDATE_IN_PROGRESS , CARD_CLOSED ); unfreezing an active card succeeds without change. For a physical card this also marks the card order as delivered.

### Entities
List the company's legal entities.

- [List company entities](https://light.inc/docs/api-reference/v1--entities/list-company-entities): `GET /v1/entities` — Returns a paginated list of company entities
  - NOTE: Without a filter , inactive entities are hidden (the default is status:in:ACTIVE HIDDEN ). Any filter you send replaces that default entirely , so filter=code:eq:001 will also return an INACTIVE entity — add status:ne:INACTIVE yourself when combining filters. HIDDEN entities are hidden in the app but usable. Default order is the app's own ordering ( sortPosition:asc ), not name or code . includeCardCustomer has no effect on the response body.

### Companies
Access company configuration, such as currency settings.

- [Get current company](https://light.inc/docs/api-reference/v1--companies/get-current-company): `GET /v1/companies/current` — Returns the current company information
  - NOTE: Returns the company the credential belongs to. baseCurrency is the group (reporting) currency; each entity has its own localCurrency on GET /v1/entities . The four email fields are the company's inbound mailboxes: documents emailed to them are ingested by Light. There is no fiscal-year information on this endpoint.

### Contracts
Create, publish, renew, terminate and manage contracts.

- [Cancel scheduled termination](https://light.inc/docs/api-reference/v1--contracts/cancel-scheduled-termination): `POST /v1/contracts/{contractId}/cancel-termination` — Cancels a scheduled termination, returning the contract to active
  - NOTE: Only from PENDING_TERMINATION ; no scheduled termination is 404 CONTRACT_TERMINATION_REQUEST_NOT_FOUND .
- [List contracts](https://light.inc/docs/api-reference/v1--contracts/list-contracts): `GET /v1/contracts` — Returns a paginated list of contracts
  - NOTE: The filter parameter does accept fields , despite the empty list below: companyEntityId , customerId , id , state and updatedAt . There is no default filter (contracts of every state are returned), no searchTerm and no default order. lines is [] in list rows; only GET /v1/contracts/{contractId} returns them.
- [Create contract](https://light.inc/docs/api-reference/v1--contracts/create-contract): `POST /v1/contracts` — Creates a new contract
  - NOTE: A new contract is in DRAFT , not CREATED ; CREATED is the transient state of a PDF uploaded for parsing in the app. Defaults: netTerms 30, invoiceLeadDays 0 (must be 0 to 365), areLinesWithTax true . Line billingStart falls back to the contract's, and line account and tax fields to the product's defaults for the tax engine in force. Bank account, accounts, tax codes and template must belong to companyEntityId . With an X-Idempotency-Key a replay returns the same contract and a different body is 409 IDEMPOTENCY_VIOLATION ; without one nothing is de-duplicated.
- [Create contract line](https://light.inc/docs/api-reference/v1--contracts/create-contract-line): `POST /v1/contracts/{contractId}/lines` — Creates a new contract line item
  - NOTE: Only while the contract is DRAFT ( CONTRACT_CANNOT_BE_MODIFIED ). A line discount carries its own startDate and endDate window in addition to type and value .
- [Get contract](https://light.inc/docs/api-reference/v1--contracts/get-contract): `GET /v1/contracts/{contractId}` — Returns a specific contract by ID
  - NOTE: Any status. An unknown id, or one from another company, is 404 .
- [Delete contract](https://light.inc/docs/api-reference/v1--contracts/delete-contract): `DELETE /v1/contracts/{contractId}` — Deletes a contract by ID
  - NOTE: Only a never-published DRAFT can be deleted ( CONTRACT_CANNOT_BE_DELETED otherwise). Use terminate for an active contract.
- [Update contract](https://light.inc/docs/api-reference/v1--contracts/update-contract): `PATCH /v1/contracts/{contractId}` — Updates a contract
  - NOTE: Only while DRAFT . An ACTIVE contract cannot be edited through this API (there is no endpoint to open a working version): every change fails with CONTRACT_CANNOT_BE_MODIFIED , and the only routes are reset (back to DRAFT , with its side effects) or renew . Unlike most PATCH bodies, null clears nearly every field here, including startDate , endDate , customerId and netTerms . Changing billingStart moves every line whose billingStart matched the old value; changing companyEntityId drops a bank account or template that doesn't belong to the new entity and re-resolves line accounts and taxes.
- [Delete contract line](https://light.inc/docs/api-reference/v1--contracts/delete-contract-line): `DELETE /v1/contracts/{contractId}/lines/{lineId}` — Deletes a contract line item
  - NOTE: Only while the contract is DRAFT ( CONTRACT_CANNOT_BE_MODIFIED ); unknown line is 404 CONTRACT_LINE_NOT_FOUND .
- [Update contract line](https://light.inc/docs/api-reference/v1--contracts/update-contract-line): `PATCH /v1/contracts/{contractId}/lines/{lineId}` — Updates a contract line item
  - NOTE: Only while the contract is DRAFT ( CONTRACT_CANNOT_BE_MODIFIED ). null clears billingEnd , discount , priceOverwrite , productNameOverwrite , quantity and the amortization fields, but leaves productId , billingStart , accountId , taxCodeId and billingRecurrence unchanged.
- [Generate document upload URL](https://light.inc/docs/api-reference/v1--contracts/generate-document-upload-url): `POST /v1/contracts/{contractId}/generate-document-upload-url` — Generates a pre-signed URL to upload the main contract document (PDF). After uploading to this URL, the document will appear in the contract's document preview.
  - NOTE: Only while the contract is DRAFT ( CONTRACT_CANNOT_BE_MODIFIED ). PUT the PDF to uploadUrl within five minutes with Content-Type: application/pdf and every entry of metadata as a request header (see Files (/docs/getting-started/pagination-filtering-errors files)). The file is attached asynchronously, and only if the contract is still editable at that moment; otherwise it is dropped. Nothing on this API shows the result: GET /v1/contracts/{contractId} has no document field, and the upload does not trigger any parsing or change any field.
- [List contract activity events](https://light.inc/docs/api-reference/v1--contracts/list-contract-activity-events): `GET /v1/contracts/{contractId}/activity-events` — The contract's activity timeline, newest first: who did what to it, when, and which fields changed. Requires permission to view this contract. The entityId and entityType filters are fixed by the path here; passing them can only narrow the result.
- [Publish contract](https://light.inc/docs/api-reference/v1--contracts/publish-contract): `POST /v1/contracts/{contractId}/publish` — Publishes a contract, transitioning it to ACTIVE state
  - NOTE: Required before publishing ( CONTRACT_DETAILS_MISSING_FIELD , CONTRACT_LINE_MISSING_FIELD , CONTRACT_MISSING_LINES ): netTerms , billingStart , companyEntityId , currency , customerId , invoiceTemplateId , paymentType , startDate , a bank account for bank transfer or direct debit, and at least one line with accountId , billingStart , quantity and a tax code for the engine in force. endDate is optional (open-ended contract). Each product needs a price in the contract currency unless priceOverwrite is set, the schedule must total above zero, and the contract may not run longer than 100 years. Publishing moves the contract to ACTIVE and immediately generates every invoice whose billing date has already passed, as DRAFT invoice receivables linked by contractId . From then on a daily job creates each next invoice seven days before its billing date, also as DRAFT , with postingDate on the planned invoice date and dueDate that many netTerms later. Nothing opens or sends them: open each with POST /v1/invoice-receivables/{invoiceReceivableId}/open . The same job terminates a contract whose endDate has passed without a renewalDate . Publishing an ACTIVE contract again with no changes fails with CONTRACT_CANNOT_BE_PUBLISHED .
- [Renew contract](https://light.inc/docs/api-reference/v1--contracts/renew-contract): `POST /v1/contracts/{contractId}/renew` — Renews a contract by extending its end date
  - NOTE: Only from ACTIVE , and only for a contract that has an endDate ( CONTRACT_CANNOT_RENEW_WITH_NO_END_DATE ). nextEndDate must be on or after both the current endDate and today. It sets endDate , sets renewalDate to nextRenewalDate or clears it when omitted , and extends only the lines whose billingEnd equalled the old endDate ; lines ending earlier are left alone. The renewal re-runs every publish validation.
- [Reset contract](https://light.inc/docs/api-reference/v1--contracts/reset-contract): `POST /v1/contracts/{contractId}/reset` — Resets a contract to CREATED state
  - NOTE: Returns the contract to DRAFT (the description says CREATED ), and only from ACTIVE . Side effects: every DRAFT invoice the schedule generated is archived, and every invoice, including opened ones, is unlinked from the contract ( contractId cleared); opened invoices are otherwise untouched.
- [Terminate contract](https://light.inc/docs/api-reference/v1--contracts/terminate-contract): `POST /v1/contracts/{contractId}/terminate` — Terminates a contract
  - NOTE: terminationDate defaults to today. On an ACTIVE contract a future date schedules the termination: state PENDING_TERMINATION , terminatedAt stays null , invoices keep being generated, and a daily job completes it on the date. A date up to today (or a DRAFT contract) terminates immediately, with terminatedAt set to that date at 00:00 UTC; back-dating is allowed down to startDate ( CONTRACT_TERMINATION_DATE_BEFORE_START_DATE ), and a scheduled date past endDate fails with CONTRACT_TERMINATION_DATE_AFTER_END_DATE . Calling it again while PENDING_TERMINATION fails with CONTRACT_INVALID_STATE_TRANSITION ; cancel the scheduled termination first. TERMINATED is terminal.

### Credit Notes
Create and list credit notes, and link them to invoice payables.

- [Archive credit note](https://light.inc/docs/api-reference/v1--credit-notes/archive-credit-note): `POST /v1/credit-notes/{creditNoteId}/archive` — Archives the credit note. If the credit note has been posted, it will be reversed in the ledger. A credit note with active links to invoice payables cannot be archived — unlink first.
  - NOTE: A posted credit note is reversed in the ledger and ends in ARCHIVED , not back in DRAFT , and there is no unarchive. A POSTED note with links fails with CREDIT_NOTE_CANNOT_BE_ARCHIVED_WHEN_LINKED : unlink it first, which also reverses any clearing.
- [List credit notes](https://light.inc/docs/api-reference/v1--credit-notes/list-credit-notes): `GET /v1/credit-notes` — Returns a paginated list of credit notes
  - NOTE: The accounting documents list restricted to CN : same filters and sorts, default order newest first, drafts and archived notes included unless filtered.
- [Create credit note](https://light.inc/docs/api-reference/v1--credit-notes/create-credit-note): `POST /v1/credit-notes` — Creates a new credit note in draft status. The credit note can be created with or without line items. When documentNumber is provided, it is used for idempotency — retrying a create with the same documentNumber returns the existing credit note instead of creating a duplicate. The areLinesWithTax field controls whether line amounts include tax (true = gross, tax included) or exclude tax (false = net, tax added on top). A businessPartnerId (vendor) is required if the credit note will be linked to an invoice payable later. The posting date is automatically set to the documentDate .
  - NOTE: Created in DRAFT . documentDate is also the posting date; areLinesWithTax defaults to true . Line amounts are { amount, dcSign } objects and a credit note's lines are credits ( "dcSign": "C" ): at post the total must be a credit ( CREDIT_NOTE_NEGATIVE_TOTAL_AMOUNT ). Idempotency: an X-Idempotency-Key header wins; without one the key is derived from documentNumber , so re-sending the same number with a different body is 409 IDEMPOTENCY_VIOLATION . A credit note created here has no PDF , so GET .../document redirects to a file that doesn't exist. Requires a user credential.
- [Create credit note line](https://light.inc/docs/api-reference/v1--credit-notes/create-credit-note-line): `POST /v1/credit-notes/{creditNoteId}/lines` — Creates a new line item on a credit note in draft status.
  - NOTE: Only while the credit note is DRAFT ( CREDIT_NOTE_CANNOT_BE_MODIFIED ). Amounts are { amount, dcSign } objects, normally credits ( C ). costCenterId cannot be set through the API.
- [Create credit note from invoice payable](https://light.inc/docs/api-reference/v1--credit-notes/create-credit-note-from-invoice-payable): `POST /v1/credit-notes/create-from-invoice-payable/{invoicePayableId}` — Creates a credit note from an existing invoice payable
  - NOTE: Destructive : the invoice payable is deleted (a later GET on it is 404 ) and replaced by a DRAFT credit note that copies its entity, vendor, currency, dates, FX overrides, document and lines, with documentNumber set to the invoice number and every amount made positive. The bill must be a vendor or self-billed invoice in IN_DRAFT , have an uploaded document, and have no credit notes linked ( INVALID_INVOICE_PAYABLE_FOR_CREDIT_NOTE ).
- [Delete credit note line](https://light.inc/docs/api-reference/v1--credit-notes/delete-credit-note-line): `DELETE /v1/credit-notes/{creditNoteId}/lines/{lineId}` — Deletes a line item from a credit note in draft status.
  - NOTE: Only while the credit note is DRAFT ( CREDIT_NOTE_CANNOT_BE_MODIFIED ). Answers 204 with no body.
- [Update credit note line](https://light.inc/docs/api-reference/v1--credit-notes/update-credit-note-line): `PATCH /v1/credit-notes/{creditNoteId}/lines/{lineId}` — Updates a line item on a credit note in draft status. Fields sent as null clear the value; omitted fields remain unchanged.
  - NOTE: Only while the credit note is DRAFT ( CREDIT_NOTE_CANNOT_BE_MODIFIED ). null clears every field except customProperties , which null leaves unchanged.
- [Get credit note](https://light.inc/docs/api-reference/v1--credit-notes/get-credit-note): `GET /v1/credit-notes/{creditNoteId}` — Returns a credit note by ID
  - NOTE: Includes lines. An unknown id, or one from another company, is 404 .
- [Update credit note](https://light.inc/docs/api-reference/v1--credit-notes/update-credit-note): `PATCH /v1/credit-notes/{creditNoteId}` — Updates a credit note in draft status. Fields sent as null clear the value; omitted fields remain unchanged.
  - NOTE: Only in DRAFT ( CREDIT_NOTE_CANNOT_BE_MODIFIED ). The null rule in the description holds for description , currency , amount , documentNumber and the FX overrides only; companyEntityId , businessPartnerId , documentDate , areLinesWithTax and customProperties cannot be cleared — null leaves them unchanged. Changing businessPartnerId silently clears companyEntityId when the entity isn't one the new vendor is enabled for. documentDate also rewrites the posting date.
- [List credit note activity events](https://light.inc/docs/api-reference/v1--credit-notes/list-credit-note-activity-events): `GET /v1/credit-notes/{creditNoteId}/activity-events` — The credit note's activity timeline, newest first: who did what to it, when, and which fields changed. Requires permission to view this credit note. The entityId and entityType filters are fixed by the path here; passing them can only narrow the result.
- [Get credit note document](https://light.inc/docs/api-reference/v1--credit-notes/get-credit-note-document): `GET /v1/credit-notes/{creditNoteId}/document` — Returns the attached PDF document for a credit note
  - NOTE: Answers 307 Temporary Redirect to a pre-signed URL, not the file. A credit note created through this API has no PDF behind that URL; only notes created from an uploaded document have one.
- [Get linked invoice payables](https://light.inc/docs/api-reference/v1--credit-notes/get-linked-invoice-payables): `GET /v1/credit-notes/{creditNoteId}/invoice-payables` — Returns all invoice payables linked to the credit note
  - NOTE: Not paginated: every bill the credit note is linked to, in one list.
- [Link credit note to invoice payable](https://light.inc/docs/api-reference/v1--credit-notes/link-credit-note-to-invoice-payable): `POST /v1/credit-notes/{creditNoteId}/invoice-payables/{invoicePayableId}` — Links a credit note to an invoice payable for clearing (offsetting balances). Because credit notes cannot be applied in the ledger until the invoice payable is posted, this creates a 'link' record that will be used during posting to automatically clear the credit note balance against the invoice payable balance. Requirements: credit note must be in POSTED status, both documents must belong to the same company entity, same vendor (businessPartnerId), same currency, and clearing amount cannot exceed available balance on either document.
  - NOTE: The credit note must be POSTED (or PARTIALLY_CLEARED ); a draft fails with CREDIT_NOTE_CANNOT_BE_LINKED_UPDATED_UNLINKED . What the link does depends on the bill's state. A bill in IN_DRAFT or APPROVAL_PENDING only records the link, applied when the bill is posted; a posted, unpaid bill ( UNPAID , READY_FOR_PAYMENT_RELEASE , SCHEDULED , PENDING_PAYMENT_APPROVAL ) is cleared immediately and moves to PARTIALLY_PAID or COMPLETED — the response doesn't show that, so re-read the bill. amount has no default: it must be above zero ( INVALID_LINKING_AMOUNT ), within the note's unallocated amount ( CREDIT_NOTE_AMOUNT_EXCEEDED ), and for a posted bill within its remaining balance. Vendor, entity and currency must match; a pair already linked is CREDIT_NOTE_ALREADY_LINKED .
- [Unlink credit note from invoice payable](https://light.inc/docs/api-reference/v1--credit-notes/unlink-credit-note-from-invoice-payable): `DELETE /v1/credit-notes/{creditNoteId}/invoice-payables/{invoicePayableId}` — Removes the link between a credit note and an invoice payable
  - NOTE: On a bill the note has already cleared ( PARTIALLY_PAID , COMPLETED ) or an UNPAID bill, the clearing is reversed in the ledger and the bill returns to UNPAID or PARTIALLY_PAID ; on a draft bill only the link row is removed.
- [Update clearing amount](https://light.inc/docs/api-reference/v1--credit-notes/update-clearing-amount): `PATCH /v1/credit-notes/{creditNoteId}/invoice-payables/{invoicePayableId}` — Updates the clearing amount of a linked invoice payable
  - NOTE: Only while the link has not been applied, i.e. the bill is still a draft or awaiting approval; once the bill is PARTIALLY_PAID or COMPLETED through this note the call fails with INVOICE_PAYABLE_CANNOT_BE_LINKED_UPDATED_UNLINKED . Unlink and relink instead. Sending the current amount is a no-op.
- [Post credit note](https://light.inc/docs/api-reference/v1--credit-notes/post-credit-note): `POST /v1/credit-notes/{creditNoteId}/post` — Posts the credit note to the ledger. The credit note must be in draft status with at least one line item. A valid companyEntityId , businessPartnerId , and currency are required. After posting, the credit note can be linked to invoice payables for balance clearing.
  - NOTE: Beyond the listed prerequisites: the company must use Light's ledger ( CREDIT_NOTE_CANNOT_BE_POSTED ), amount must be set and non-zero and equal the sum of the lines' gross amounts ( CREDIT_NOTE_VALIDATION_ERROR ), the total must be a credit ( CREDIT_NOTE_NEGATIVE_TOTAL_AMOUNT ), and every line needs ledgerAccountId ( CREDIT_NOTE_MISSING_FIELD ). businessPartnerId is not actually checked here; it is required to link. The posting needs an open period and a payables control account for the entity. If the company auto-allocates credits, the response may already be PARTIALLY_CLEARED or CLEARED .

### Custom Properties
Access custom property groups.

- [List custom property values](https://light.inc/docs/api-reference/v1--custom-properties/list-custom-property-values): `GET /v1/custom-properties/groups/{groupId}/values` — Returns a paginated list of custom property values
  - NOTE: Lists catalogue values only; inline (free-text) values written on records are never returned. Values deleted with DELETE .../values/{valueId} are still returned here and cannot be told apart, because the value model carries no status, whereas the group endpoints hydrate active values only. The value filter and sort field matches internalName . An unknown groupId yields an empty page, not 404 .
- [Create custom property value](https://light.inc/docs/api-reference/v1--custom-properties/create-custom-property-value): `POST /v1/custom-properties/groups/{groupId}/values` — Creates a new custom property value in the specified group
  - NOTE: internalName must match ^[a-z0-9_-]+$ ( CUSTOM_PROPERTY_VALUES_INVALID_INTERNAL_NAMES ), must be unique within the group ( CUSTOM_PROPERTY_VALUE_ALREADY_EXISTS ) and cannot be changed later. Blank internalName or label are rejected ( CUSTOM_PROPERTY_VALUE_EMPTY_INTERNAL_NAME , CUSTOM_PROPERTY_VALUE_EMPTY_LABEL ). The group's inputType is not checked, so you can add catalogue values to a TEXT , NUMERIC , DATE or BOOLEAN group; records then reference them through valueIds . Requires the company-admin role.
- [Get custom property value](https://light.inc/docs/api-reference/v1--custom-properties/get-custom-property-value): `GET /v1/custom-properties/groups/{groupId}/values/{valueId}` — Returns a custom property value by ID
  - NOTE: 404 unless the value belongs to that group.
- [Delete custom property value](https://light.inc/docs/api-reference/v1--custom-properties/delete-custom-property-value): `DELETE /v1/custom-properties/groups/{groupId}/values/{valueId}` — Deletes a custom property value by ID
  - NOTE: A soft delete with no in-use check: records that reference the value keep it, and the value keeps appearing on GET .../values (it disappears from the group's hydrated values ). Repeating the call succeeds again. Answers 204 with no body. Requires the company-admin role.
- [Update custom property value](https://light.inc/docs/api-reference/v1--custom-properties/update-custom-property-value): `PATCH /v1/custom-properties/groups/{groupId}/values/{valueId}` — Updates an existing custom property value
  - NOTE: label cannot be cleared: sending null leaves it unchanged. context follows the usual rule (omit to keep, null or "" to clear). A value that doesn't belong to the given groupId is 404 CUSTOM_PROPERTY_VALUE_NOT_FOUND . Requires the company-admin role.
- [Get custom property group](https://light.inc/docs/api-reference/v1--custom-properties/get-custom-property-group): `GET /v1/custom-properties/groups/{groupId}` — Returns a custom property group by ID
  - NOTE: Always includes values , restricted to active values. A group that was deleted in Light still answers 200 (see the list endpoint for how to tell); only groups your company defined are visible, everything else is 404 CUSTOM_PROPERTY_GROUP_NOT_FOUND .
- [List custom property groups](https://light.inc/docs/api-reference/v1--custom-properties/list-custom-property-groups): `GET /v1/custom-properties/groups` — Returns a paginated list of custom property groups
  - NOTE: Only groups your company defined are listed; Light's system-provided definitions never appear here. values is null unless includeValues=true , and even then only active values are included, capped at 15,000 per group — a larger catalogue comes back with an empty values , so use GET .../groups/{groupId}/values for those. There is no status on a group. A group deleted in Light is still listed : every entry of its objectTypeStatuses reads DELETED . Exclude those with filter=isDeleted:eq:false . Two filter quirks: objectType:in:INVOICE BILL matches groups enabled for all of the listed types, not any of them; and objectTypeStatus on its own matches a group where any record type has that status — pair it with objectType to scope it. Default order is label:asc .

### Customer Credits
Manage customer credit documents.

- [Archive customer credit](https://light.inc/docs/api-reference/v1--customer-credits/archive-customer-credit): `POST /v1/customer-credits/{customerCreditId}/archive` — Archives the given customer credit
  - NOTE: From DRAFT it simply archives; from POSTED it reverses the ledger posting first. A PARTIALLY_CLEARED or CLEARED credit cannot be archived ( ACCOUNTING_DOCUMENT_CANNOT_BE_ARCHIVED ): unlink it from its invoices first.
- [List customer credits](https://light.inc/docs/api-reference/v1--customer-credits/list-customer-credits): `GET /v1/customer-credits` — Returns a paginated list of customer credits
  - NOTE: Cursor pagination only: there is no offset , no total , and prevCursor is always null . Rows include lines . linkedInvoiceReceivable is populated only with include=INVOICE_RECEIVABLE and exactly one linked invoice; with two or more links it is null . Statuses a credit actually uses: DRAFT , POSTED , PARTIALLY_CLEARED , CLEARED , ARCHIVED .
- [Create customer credit](https://light.inc/docs/api-reference/v1--customer-credits/create-customer-credit): `POST /v1/customer-credits` — Creates a new customer credit
  - NOTE: documentNumber is assigned when the credit is posted , not "when the invoice is opened" as the description says. documentDate is also used as the posting date. lines and areLinesWithTax are required, though lines may be [] . Line amounts are { amount, dcSign } objects; for a credit the gross line amount is normally a debit ( "dcSign": "D" ). Omitted line tax and account fields take the product's defaults for the tax engine in force. Requires a user credential. An X-Idempotency-Key makes retries safe; without one nothing is de-duplicated.
- [Create customer credit line](https://light.inc/docs/api-reference/v1--customer-credits/create-customer-credit-line): `POST /v1/customer-credits/{customerCreditId}/lines` — Creates a new line for the given customer credit
  - NOTE: Only while the credit is DRAFT ( CUSTOMER_CREDIT_CANNOT_BE_MODIFIED ). ledgerTaxId only with Light's tax engine, avataxCode only with Avalara ( CUSTOMER_CREDIT_INVALID_TAX_UPDATE ).
- [Delete customer credit line](https://light.inc/docs/api-reference/v1--customer-credits/delete-customer-credit-line): `DELETE /v1/customer-credits/{customerCreditId}/lines/{lineId}` — Deletes the given customer credit line
  - NOTE: Only while the credit is DRAFT . Answers with an empty body.
- [Update customer credit line](https://light.inc/docs/api-reference/v1--customer-credits/update-customer-credit-line): `PATCH /v1/customer-credits/{customerCreditId}/lines/{lineId}` — Updates the given customer credit line
  - NOTE: Only while the credit is DRAFT . null clears the amounts, description , ledgerTaxId , ledgerAccountId , avataxCode and the accrual fields, but leaves productId and quantity unchanged. Unknown line: CUSTOMER_CREDIT_LINE_NOT_FOUND .
- [Get customer credit](https://light.inc/docs/api-reference/v1--customer-credits/get-customer-credit): `GET /v1/customer-credits/{customerCreditId}` — Returns a customer credit by ID
  - NOTE: Always includes lines and, when there is exactly one linked invoice, linkedInvoiceReceivable .
- [Update customer credit](https://light.inc/docs/api-reference/v1--customer-credits/update-customer-credit): `PATCH /v1/customer-credits/{customerCreditId}` — Updates the given customer credit
  - NOTE: Only in DRAFT ( CUSTOMER_CREDIT_CANNOT_BE_MODIFIED ). null clears description , currency , amount , documentNumber and documentTemplateId but leaves companyEntityId , customerId , documentDate and areLinesWithTax unchanged; documentDate also rewrites the posting date. While any invoice is linked, customerId , companyEntityId and currency cannot change ( CUSTOMER_CREDIT_CANNOT_CHANGE_SCOPE_WHILE_LINKED ) and amount cannot drop below the linked total ( CUSTOMER_CREDIT_AMOUNT_BELOW_LINKED_SUM ).
- [List customer credit activity events](https://light.inc/docs/api-reference/v1--customer-credits/list-customer-credit-activity-events): `GET /v1/customer-credits/{customerCreditId}/activity-events` — The customer credit's activity timeline, newest first: who did what to it, when, and which fields changed. Requires permission to view this customer credit. The entityId and entityType filters are fixed by the path here; passing them can only narrow the result.
- [Link customer credit to invoice](https://light.inc/docs/api-reference/v1--customer-credits/link-customer-credit-to-invoice): `POST /v1/customer-credits/{customerCreditId}/invoice-receivables/{invoiceReceivableId}/link` — Links a customer credit to a sales invoice
  - NOTE: Identical to POST .../invoice-receivables/{invoiceReceivableId} ; this is the newer path. When the credit is applied depends on its status : linking a POSTED credit clears the invoice immediately (it moves to PARTIALLY_PAID or PAID in this call), while linking a DRAFT credit only records the link, applied when the credit is posted. Requirements: invoice OPEN or PARTIALLY_PAID ; credit DRAFT or POSTED ; same customer, entity and currency; the credit's header amount set ( CUSTOMER_CREDIT_AMOUNT_NOT_SET ); not already linked ( CUSTOMER_CREDIT_ALREADY_LINKED ). The description of amount has it backwards: partial allocation is a capability granted by the entity's e-invoicing configuration, and an entity without one gets one link per credit with amount omitted or equal to the whole available credit ( CUSTOMER_CREDIT_PARTIAL_ALLOCATION_NOT_ENABLED ). The response's amount is what was actually linked: the requested amount, else the smaller of the credit and the invoice balance.
- [Link customer credit](https://light.inc/docs/api-reference/v1--customer-credits/link-customer-credit): `POST /v1/customer-credits/{customerCreditId}/invoice-receivables/{invoiceReceivableId}` — Links a customer credit to a sales invoice
  - NOTE: Identical to POST .../invoice-receivables/{invoiceReceivableId}/link , which is the newer path; see that endpoint for when the credit is applied and what is validated.
- [Unlink customer credit](https://light.inc/docs/api-reference/v1--customer-credits/unlink-customer-credit): `DELETE /v1/customer-credits/{customerCreditId}/invoice-receivables/{invoiceReceivableId}` — Deprecated: Use POST /{customerCreditId}/invoice-receivables/{invoiceReceivableId}/unlink instead. Unlinks a customer credit from a sales invoice. If the customer credit has already been applied (CLEARED or PARTIALLY_CLEARED status), this will reverse the clearing entries in the ledger.
  - NOTE: Identical to POST .../invoice-receivables/{invoiceReceivableId}/unlink ; only the path is deprecated. If the credit has already been applied, the clearing on the invoice is reversed first (the invoice goes back to OPEN or PARTIALLY_PAID ) and the credit returns to POSTED . Answers with an empty body.
- [Post and send customer credit](https://light.inc/docs/api-reference/v1--customer-credits/post-and-send-customer-credit): `POST /v1/customer-credits/{customerCreditId}/post-and-send-email` — Posts the customer credit and sends it via email. Optionally submits to e-invoicing if shouldSubmitEInvoice is set.
  - NOTE: Same as post , plus a required emailInfo that is validated before posting, so a bad subject or recipient list leaves the credit in DRAFT ( CUSTOMER_CREDIT_EMAIL_INVALID_SUBJECT , CUSTOMER_CREDIT_EMAIL_MISSING_RECIPIENTS , at most 20 recipients and 20 cc). The email itself is sent after the call returns.
- [Post customer credit](https://light.inc/docs/api-reference/v1--customer-credits/post-customer-credit): `POST /v1/customer-credits/{customerCreditId}/post` — Posts the given customer credit and applies to invoice if linked
  - NOTE: Only from DRAFT , and only when the company's ledger is enabled ( CUSTOMER_CREDIT_CANNOT_BE_POSTED ). The body is optional. Posting assigns documentNumber if empty, writes the ledger entries, applies every link recorded while the credit was a draft (those invoices move to PARTIALLY_PAID or PAID , the credit to PARTIALLY_CLEARED or CLEARED ), and, if the company auto-allocates credits, may apply the remainder to the customer's other open invoices. An e-credit-note is queued when shouldSubmitEInvoice is true , or when it is omitted and a linked invoice was e-invoiced; true on an entity without that capability fails synchronously with CUSTOMER_CREDIT_E_INVOICING_NOT_ENABLED . The response reflects the state after links are applied.
- [Submit e-invoice for customer credit](https://light.inc/docs/api-reference/v1--customer-credits/submit-e-invoice-for-customer-credit): `POST /v1/customer-credits/{customerCreditId}/submit-einvoice` — Submits an e-invoice for the given customer credit. The customer credit must be posted.
  - NOTE: The credit must be posted ( CUSTOMER_CREDIT_INVALID_STATUS_FOR_EINVOICE_SUBMISSION ), not already submitted ( CUSTOMER_CREDIT_EINVOICE_ALREADY_SUBMITTED ), and its entity must have e-credit-note submission enabled ( CUSTOMER_CREDIT_E_INVOICING_NOT_ENABLED ). Unlike post , the submission runs synchronously inside this call. Returns an empty body.
- [Unarchive customer credit](https://light.inc/docs/api-reference/v1--customer-credits/unarchive-customer-credit): `POST /v1/customer-credits/{customerCreditId}/unarchive` — Unarchives the given customer credit and reverts it to draft
  - NOTE: Only from ARCHIVED ( CUSTOMER_CREDIT_INVALID_STATUS_FOR_UNARCHIVE ). Lands in DRAFT and deletes every invoice link the credit still had.
- [Unlink customer credit from invoice](https://light.inc/docs/api-reference/v1--customer-credits/unlink-customer-credit-from-invoice): `POST /v1/customer-credits/{customerCreditId}/invoice-receivables/{invoiceReceivableId}/unlink` — Unlinks a customer credit from a sales invoice. If the customer credit has already been applied (CLEARED or PARTIALLY_CLEARED status), this will reverse the clearing entries in the ledger.
  - NOTE: If the credit has already been applied, the clearing on the invoice is reversed first (the invoice goes back to OPEN or PARTIALLY_PAID ) and the credit returns to POSTED . A link that doesn't exist is CUSTOMER_CREDIT_INVOICE_RECEIVABLE_NOT_FOUND . Answers with an empty body.

### Customers
Customers are entities that purchase goods or services from a company. They can be used on invoices and contracts.

- [Activate customer](https://light.inc/docs/api-reference/v1--customers/activate-customer): `POST /v1/customers/{customerId}/activate` — Activate the given customer
  - NOTE: Idempotent: activating an active customer returns 200 unchanged.
- [Archive customer](https://light.inc/docs/api-reference/v1--customers/archive-customer): `POST /v1/customers/{customerId}/archive` — Archive the given customer
  - NOTE: Idempotent: archiving an archived customer returns 200 unchanged. Existing invoices and contracts are not affected, but the customer can no longer be updated until activated again. Statuses are ACTIVE and ARCHIVED .
- [List customers](https://light.inc/docs/api-reference/v1--customers/list-customers): `GET /v1/customers` — Returns a paginated list of customers
  - NOTE: Default order is name:asc ; searchTerm is supported.
- [Create customer](https://light.inc/docs/api-reference/v1--customers/create-customer): `POST /v1/customers` — Creates a new customer
  - NOTE: Nothing is checked for uniqueness: the same name, email or VAT number can be created any number of times, so de-duplicate on your side. address is a deprecated alias of billingAddress (one value, returned under both names). email must be a valid address ( CUSTOMER_INVALID_EMAIL ). For a French billing address the VAT number and registration number are cross-checked ( CUSTOMER_INVALID_FRENCH_IDENTIFIERS ) and a missing SIREN is derived from the VAT number. Created ACTIVE .
- [Get customer](https://light.inc/docs/api-reference/v1--customers/get-customer): `GET /v1/customers/{customerId}` — Returns a customer by ID
  - NOTE: Returns the customer whatever its status, archived included. An unknown id, or one from another company, is 404 .
- [Update customer](https://light.inc/docs/api-reference/v1--customers/update-customer): `PATCH /v1/customers/{customerId}` — Updates an existing customer
  - NOTE: An ARCHIVED customer cannot be updated ( CUSTOMER_CANNOT_BE_MODIFIED ); activate it first. null clears shippingAddress , domain , description , vatNumber , businessRegistrationNumber , the e-invoicing fields, type and logoUrl , but leaves name , email and the billing address unchanged. recipientEmails and ccEmails : omit to keep, [] to clear.
- [List customer activity events](https://light.inc/docs/api-reference/v1--customers/list-customer-activity-events): `GET /v1/customers/{customerId}/activity-events` — The customer's activity timeline, newest first: who did what to it, when, and which fields changed. Requires permission to view this customer. The entityId and entityType filters are fixed by the path here; passing them can only narrow the result.

### Exchange
Retrieve currency exchange rates.

- [Get exchange rate](https://light.inc/docs/api-reference/v1--exchange/get-exchange-rate): `GET /v1/exchange/rates/{base}/{target}` — Returns an exchange rate between base and target currencies for a given date
  - NOTE: rate is the number of target units per one unit of base ( amountInTarget = amountInBase × rate ). Rates are the European Central Bank's daily reference rates (a second provider covers currencies the ECB doesn't publish), stored by Light once a day and served from that store: the endpoint never calls a provider live, and company-specific rate overrides are ignored. date omitted means today; a future date is clamped to the latest stored day ( effectiveDate says which); weekends and holidays resolve to the last published rate. A past date with no stored row fails with EXCHANGE_RATE_NOT_AVAILABLE .
- [Get currency exchange rates](https://light.inc/docs/api-reference/v1--exchange/get-currency-exchange-rates): `GET /v1/exchange/rates/{currency}` — Returns exchange rates for the given currency against all available currencies
  - NOTE: Same source and date handling as the pair endpoint: one entry per currency available on the resolved date, including currency itself at 1 . Any currency missing on that date fails the whole request with EXCHANGE_RATE_NOT_AVAILABLE .

### Expenses
List expenses and submit reimbursements.

- [Cancel expense](https://light.inc/docs/api-reference/v1--expenses/cancel-expense): `POST /v1/expenses/{expenseId}/cancel` — Cancels an existing expense
  - NOTE: Allowed only in IN_DRAFT or CREATED ; a submitted expense fails with EXPENSE_NOT_EDITABLE . CANCELLED is terminal.
- [List expenses](https://light.inc/docs/api-reference/v1--expenses/list-expenses): `GET /v1/expenses` — Returns a paginated list of expenses
  - NOTE: A credential with only the reimbursement role must filter userId:eq:<its own user id or it receives 403 ; company-admin and auditor roles see everything. billingAmountTotal sums the lines of the whole filtered set , not just the page. Statuses: CREATED (receipt uploaded, OCR pending), IN_DRAFT , SUBMITTED_FOR_REVIEW , CANCELLED . A submission that fails downstream moves expenses back to IN_DRAFT without any call from you.
- [Create expense](https://light.inc/docs/api-reference/v1--expenses/create-expense): `POST /v1/expenses` — Creates an expense synchronously from a receipt uploaded with shouldAutoCreateExpense: false and the given line items. No OCR runs: the fields you send are what is stored. A PDF receipt is kept as-is; JPEG, PNG, HEIC and TIFF receipts are converted to PDF first. The expense is created as a draft for the authenticated user and is included in the next POST /v1/expenses/submit.
  - NOTE: Requires a user credential with the reimbursement role; under an API key it fails with USER_NOT_RECOGNIZED . The user needs an active reimbursement configuration first ( PUT /v1/users/{userId}/reimbursement-config ), or the call fails with MISSING_USER_REIMBURSEMENT_CONFIG . receiptDocumentKey must be a key from POST /v1/expenses/upload-url with shouldAutoCreateExpense: false , uploaded by the same user: anything else is 404 EXPENSE_RECEIPT_NOT_FOUND . An empty file or one over 10 MB fails with EXPENSE_RECEIPT_INVALID ; a key already used by another expense is 409 EXPENSE_RECEIPT_ALREADY_USED . Images are converted to PDF synchronously, so the stored receiptDocumentKey may differ from the one you sent. Validation ( EXPENSE_VALIDATION_FAILED , with a path per error): 1 to 50 lines, originalAmount above zero, non-blank descriptions, and each reimbursementCategoryId belonging to the user's own entity. costCenterId is ignored: every line takes the default cost centre from the user's reimbursement configuration. When originalCurrency differs from the user's reimbursement currency and no billingAmount is given, it is derived from the exchange rate on performedDate , and a missing rate fails the whole call with EXPENSE_BILLING_AMOUNT_DERIVATION_FAILED . X-Idempotency-Key is honoured per user: the same key and body returns the existing expense; the same key with a different body is 409 IDEMPOTENCY_VIOLATION . The expense is created in IN_DRAFT .
- [Create line item](https://light.inc/docs/api-reference/v1--expenses/create-line-item): `POST /v1/expenses/{expenseId}/line-items` — Creates a new line item
  - NOTE: Every field is optional here; reimbursementCategoryId , originalAmount and description only become mandatory at POST /v1/expenses/submit . What is given is validated: the category (and any accountId ) must belong to the user's entity ( EXPENSE_VALIDATION_FAILED ). billingAmount is derived from originalAmount when the expense already has a currency and date. Only while the expense is IN_DRAFT or CREATED .
- [Delete line item](https://light.inc/docs/api-reference/v1--expenses/delete-line-item): `DELETE /v1/expenses/{expenseId}/line-items/{lineItemId}` — Deletes an existing line item
  - NOTE: Only while the expense is IN_DRAFT or CREATED ( EXPENSE_NOT_EDITABLE ). Answers with an empty body.
- [Update line item](https://light.inc/docs/api-reference/v1--expenses/update-line-item): `PATCH /v1/expenses/{expenseId}/line-items/{lineItemId}` — Updates an existing expense line item
  - NOTE: Omit a field to keep it, send null to clear it. Only while the expense is IN_DRAFT or CREATED ( EXPENSE_NOT_EDITABLE ); unknown line is 404 EXPENSE_LINE_ITEM_NOT_FOUND .
- [Create upload URL](https://light.inc/docs/api-reference/v1--expenses/create-upload-url): `POST /v1/expenses/upload-url` — Creates a pre-signed URL for uploading an expense receipt document
  - NOTE: Requires a user credential with the reimbursement role; an API key is a service account, and with one the upload succeeds but no expense ever appears. The URL is valid for five minutes; PUT the bytes with the declared Content-Type and every entry of metadata as a request header (see Files (/docs/getting-started/pagination-filtering-errors files)). Two modes. With shouldAutoCreateExpense omitted or true , Light creates an expense for the uploading user in status CREATED , runs OCR, and moves it to IN_DRAFT with the extracted fields; nothing returns its id, so find it with GET /v1/expenses?filter=userId:eq:<user ,status:in:CREATED IN_DRAFT . With false , nothing happens until you call POST /v1/expenses with the returned key .
- [Get expense](https://light.inc/docs/api-reference/v1--expenses/get-expense): `GET /v1/expenses/{expenseId}` — Returns an expense by ID including all line items
  - NOTE: Includes line items. Company admins and auditors can read any expense; a user with the reimbursement role only their own. A key with neither gets 403 .
- [Update expense](https://light.inc/docs/api-reference/v1--expenses/update-expense): `PATCH /v1/expenses/{expenseId}` — Updates an existing expense
  - NOTE: Allowed only in IN_DRAFT or CREATED ( EXPENSE_NOT_EDITABLE otherwise). Both fields follow the omit-to-keep, null -to-clear rule, but sending neither fails with EMPTY_EXPENSE_UPDATE_EXCEPTION . Changing originalCurrency or performedDate recalculates every line's billingAmount from the exchange rate; clearing either sets them all to null .
- [Get expense document](https://light.inc/docs/api-reference/v1--expenses/get-expense-document): `GET /v1/expenses/{expenseId}/document` — Returns the attached receipt document as a PDF download
  - NOTE: Answers 307 Temporary Redirect to a pre-signed download URL valid for two hours, not the PDF bytes; follow it without your Light Authorization header.
- [Submit reimbursement](https://light.inc/docs/api-reference/v1--expenses/submit-reimbursement): `POST /v1/expenses/submit` — Submits all pending expenses from the current user for administrator review and approval
  - NOTE: Acts on the credential's user , so it needs a user credential with the reimbursement role; an API key fails with USER_NOT_RECOGNIZED . It submits every expense of that user in IN_DRAFT — those still in CREATED (OCR not finished) are skipped — moves them to SUBMITTED_FOR_REVIEW , creates one reimbursement in IN_PROGRESS and starts the company's approval workflow. It returns an empty body; read the result with GET /v1/users/{userId}/reimbursements/latest . With no drafts it is a silent no-op. All-or-nothing preconditions: the user has an address and postcode ( USER_MISSING_ADDRESS ); the reimbursement configuration has bank details, either domestic code and number or IBAN and BIC ( USER_INVALID_BANK_DETAILS ); and every draft has originalCurrency , performedDate , and on each line originalAmount , billingAmount , description and a category ( EXPENSE_MISSING_FIELD , EXPENSE_LINE_MISSING_FIELD ). One incomplete draft blocks the whole submission.

### General Ledger Summary
Read the general ledger summary.

- [Get general ledger summary](https://light.inc/docs/api-reference/v1--general-ledger-summary/get-general-ledger-summary): `GET /v1/general-ledger-summary` — Returns the opening balance, net movement and closing balance of every account over a date range. Each account carries one figure per entity in scope, the subtotal of those entities' own books, the intercompany elimination the selection is entitled to, and their total . Without a company entity filter the scope is every entity of the company, including inactive ones. An elimination between two entities applies only when both are in scope; one belonging to the group as a whole applies only when the scope covers the whole company.
  - NOTE: The cursor description below is wrong for this endpoint. Sending cursor=0 is rejected with {"name": "InvalidCursorException", "errors": [{"type": "INVALID_CURSOR"}]} . Omit cursor on the first request and pass nextCursor back verbatim; there is no offset parameter, no total , and prevCursor is always null . Only accountCode is sortable, and limit cannot exceed 200. Balances are debit-positive (a credit balance is negative), the opposite polarity to the signed amounts on GET /v1/ledger-transaction-lines . from and to are both required ( MISSING_PARAMETER ), from must not be after to , the opening balance covers every posting before from , and the movement covers from to to inclusive. Entity filters ( companyEntityId , companyEntityCode ) accept only eq , ne , in and not_in ( UNSUPPORTED_GENERAL_LEDGER_SUMMARY_FILTER_OPERATOR ); an entity filter that matches nothing returns rows with empty entities and zero figures. At most two concurrent calls per credential ( 429 beyond that). Reading amounts (/docs/concepts/reading-amounts) sets out the polarity rules.

### Invoice Approvals
Retrieve the approval status of an invoice.

- [Get invoice approvals](https://light.inc/docs/api-reference/v1--invoice-approvals/get-invoice-approvals): `GET /v1/invoice-approval` — Returns approval records for specified invoice payables
  - NOTE: There is no request body ; the LightPrincipal shape below is the authenticated caller leaking into the spec. invoicePayableId may be repeated and is effectively required: with none the result is an empty list, not all approvals. Only the latest approval per bill is returned, with userApprovals in priority order; a group approver has userGroupId set and userId null. Needs a user credential with the AP-preparation or auditor role, or one that is an approver on every requested bill ( 403 otherwise).

### Invoice Receivables
Invoice receivables represent a sale transaction between the company and a customer. Create, update, open, reset and send them.

- [Archive invoice](https://light.inc/docs/api-reference/v1--invoice-receivables/archive-invoice): `POST /v1/invoice-receivables/{invoiceReceivableId}/archive` — Archives an invoice receivable
  - NOTE: Only from DRAFT or OPEN ( INVOICE_RECEIVABLE_CANNOT_BE_ARCHIVED otherwise): a partially or fully paid invoice must have its clearings reversed first. Archiving an OPEN invoice reverses its ledger posting. The invoice number is retained.
- [List invoices](https://light.inc/docs/api-reference/v1--invoice-receivables/list-invoices): `GET /v1/invoice-receivables` — Returns a paginated list of invoice receivables
  - NOTE: lines is always null in list rows; only GET /v1/invoice-receivables/{invoiceReceivableId} returns them. No searchTerm and no default order. States: DRAFT (editable), OPEN_IN_PROGRESS (opening in the background), OPEN , PARTIALLY_PAID , PAID , PAYMENT_PENDING (a customer payment is in flight), ARCHIVED , and the terminal REVERSED ; CREATED is an uploaded PDF still being read and is not editable either.
- [Create invoice](https://light.inc/docs/api-reference/v1--invoice-receivables/create-invoice): `POST /v1/invoice-receivables` — Creates a new sales invoice
  - NOTE: Created in DRAFT . Defaults when omitted: postingDate is invoiceDate , else today; paymentType is BANK_TRANSFER ; currency comes from the customer, else the entity; payeeBankAccountId and invoiceTemplateId fall back to the entity's defaults; areLinesWithTax is true ; line quantity is 1 . Line tax fields must match the tax engine of the entity and customer: taxCodeId only for Light's own engine, avataxCode only for Avalara, neither for Sphere, otherwise INVOICE_RECEIVABLE_INVALID_TAX_UPDATE with the offending line in path . Every line's product needs a price in the invoice currency unless priceOverwrite is set ( INVOICE_RECEIVABLE_PRODUCT_CURRENCY_MISMATCH ); a missing product is 404 PRODUCT_NOT_FOUND even with a price override. netTerms must be 0 to 9999. Send an X-Idempotency-Key to make retries safe; without it nothing is de-duplicated, and reusing a key with a different body is 409 IDEMPOTENCY_VIOLATION . invoiceNumber stays null until the invoice is opened unless you set one.
- [Create line](https://light.inc/docs/api-reference/v1--invoice-receivables/create-line): `POST /v1/invoice-receivables/{invoiceReceivableId}/lines` — Creates a new invoice line item
  - NOTE: Only while the invoice is DRAFT ( INVOICE_RECEIVABLE_CANNOT_BE_MODIFIED ). Omitted accountId and tax fields take the product's defaults; a tax field for the wrong engine fails with INVOICE_RECEIVABLE_INVALID_TAX_UPDATE . Archived products are accepted. taxAmountOverwrite is applied once and not stored, so re-send it on any later line update that changes amounts.
- [Delete invoice line](https://light.inc/docs/api-reference/v1--invoice-receivables/delete-invoice-line): `DELETE /v1/invoice-receivables/{invoiceReceivableId}/lines/{lineId}` — Deletes an invoice line item
  - NOTE: Only while the invoice is DRAFT ( INVOICE_RECEIVABLE_CANNOT_BE_MODIFIED ). Answers with an empty body; unknown line is 404 INVOICE_RECEIVABLE_LINE_NOT_FOUND .
- [Update invoice line](https://light.inc/docs/api-reference/v1--invoice-receivables/update-invoice-line): `PATCH /v1/invoice-receivables/{invoiceReceivableId}/lines/{lineId}` — Updates an invoice line item
  - NOTE: Only while the invoice is DRAFT . null clears accountId , taxCodeId , discount , priceOverwrite , productNameOverwrite , avataxCode , billingStart , billingEnd and the accrual fields, but leaves productId , quantity and taxAmountOverwrite unchanged. Changing productId resets priceOverwrite to the new product's price unless you send one in the same request. taxAmountOverwrite is not persisted: a later update that changes quantity , priceOverwrite , discount or productId without it recalculates tax from the tax code. A discount that would make the line negative is silently dropped.
- [Generate invoice PDF](https://light.inc/docs/api-reference/v1--invoice-receivables/generate-invoice-pdf): `POST /v1/invoice-receivables/{invoiceReceivableId}/document` — Generates the PDF document for an invoice receivable. Poll this endpoint until status is READY , then use the url field to download the PDF. The signed URL is temporary and should not be stored and reused. To download again, call this endpoint to get a fresh URL.
  - NOTE: Idempotent on content: the first call answers GENERATING with url: null , and you poll this same POST until READY . A new PDF is generated only when none exists, the last attempt FAILED , or the invoice changed since; otherwise the existing one is returned with a fresh link. The url is a pre-signed link valid for five minutes . Works on drafts too, but needs invoiceTemplateId ( INVOICE_RECEIVABLE_MISSING_TEMPLATE ). If an original PDF was uploaded for the invoice, that file is returned instead of a generated one.
- [Get invoice](https://light.inc/docs/api-reference/v1--invoice-receivables/get-invoice): `GET /v1/invoice-receivables/{invoiceReceivableId}` — Returns a specific invoice receivable by ID
  - NOTE: Any state, with lines. An unknown id, or one from another company, is 404 .
- [Update invoice](https://light.inc/docs/api-reference/v1--invoice-receivables/update-invoice): `PATCH /v1/invoice-receivables/{invoiceReceivableId}` — Updates an invoice receivable
  - NOTE: Only in DRAFT ; anything else fails with INVOICE_RECEIVABLE_CANNOT_BE_MODIFIED . Sending null clears invoiceNumber , payeeBankAccountId , invoiceTemplateId , description , poNumber , reference and invoiceTemplateAdditionalText but leaves companyEntityId , currency , paymentType , invoiceDate , postingDate , dueDate , customerId , areLinesWithTax and netTerms unchanged. Three side effects to expect: with netTerms set, changing invoiceDate or postingDate moves dueDate (an explicit dueDate wins); changing companyEntityId drops a payeeBankAccountId or invoiceTemplateId that doesn't belong to the new entity; changing currency reprices every line from the product's price in that currency and removes lines whose product has no such price . The FX rates set at creation cannot be changed.
- [List invoice activity events](https://light.inc/docs/api-reference/v1--invoice-receivables/list-invoice-activity-events): `GET /v1/invoice-receivables/{invoiceReceivableId}/activity-events` — The invoice's activity timeline, newest first: who did what to it, when, and which fields changed. Requires permission to view this invoice. The entityId and entityType filters are fixed by the path here; passing them can only narrow the result.
- [List invoice payments](https://light.inc/docs/api-reference/v1--invoice-receivables/list-invoice-payments): `GET /v1/invoice-receivables/{invoiceReceivableId}/payments` — Returns a list of payments for an invoice receivable
  - NOTE: A plain array, not paginated. Each entry is a clearing on the ledger: amount and paymentDate are in the invoice currency; a bank payment ( payment.type: BP ) also carries the bank amount and currency, while a customer credit ( CC ) carries its document number. To reverse one, pass payment.accountingDocumentId to reverse-clearing ; the top-level id is the clearing event and is not accepted there.
- [Enter invoice payment](https://light.inc/docs/api-reference/v1--invoice-receivables/enter-invoice-payment): `POST /v1/invoice-receivables/{invoiceReceivableId}/payments` — Enters a payment for an invoice receivable. If the total amount paid equals the invoice total, the invoice status will be changed to PAID, otherwise it will be PARTIALLY_PAID.
  - NOTE: Only from OPEN , PARTIALLY_PAID or PAYMENT_PENDING ( INVOICE_RECEIVABLE_INVALID_STATE_TRANSITION ). Exactly one of bankAccountId (deprecated) or ledgerAccountId ( INVOICE_RECEIVABLE_MARK_AS_PAID_MISSING_ACCOUNT ). An amount above the remaining balance is rejected with INVOICE_RECEIVABLE_INVALID_PAYMENT_AMOUNT , so overpayments are impossible; the invoice becomes PAID only when the amount equals the balance exactly, PARTIALLY_PAID otherwise. A bank-payment document is created and posted to the ledger; when the bank account's currency differs from the invoice's, the company rate on paymentDate is used and a missing rate fails the call. Requires a user credential.
- [Open invoice](https://light.inc/docs/api-reference/v1--invoice-receivables/open-invoice): `POST /v1/invoice-receivables/{invoiceReceivableId}/open` — Initiates the process of opening an invoice receivable. This assigns an invoice number, locks the invoice for editing, and optionally sends it via email or submits it to e-invoicing systems. The request body is optional - if not provided, the invoice will be opened with default settings (no email sent, no e-invoice submission).
  - NOTE: Two phases. Synchronously the invoice is validated ( paymentType , dueDate , customerId , invoiceTemplateId , entity, currency, a bank account for bank transfer or direct debit, at least one line with product, account and tax, a total above zero, required custom properties — errors such as INVOICE_RECEIVABLE_DETAILS_MISSING_FIELD , INVOICE_RECEIVABLE_LINE_MISSING_FIELD , INVOICE_RECEIVABLE_MISSING_LINES ), the ledger posting is previewed against open accounting periods, the invoice number is assigned , and the response comes back in OPEN_IN_PROGRESS with invoiceNumber set. In the background the e-invoice is submitted (if requested), the email is sent (if requested), and only then is the invoice posted to the ledger and moved to OPEN with openedAt . Poll GET /v1/invoice-receivables/{invoiceReceivableId} until the state leaves OPEN_IN_PROGRESS . A validation failure in the background (for example shouldSubmitEInvoice on an entity without e-invoicing) sends it back to DRAFT with failureContext , keeping the number for the next attempt. If the company auto-allocates customer credits, an invoice can land in PARTIALLY_PAID or PAID straight away. With shouldSendEmail , emailInfo is required.
- [Reset invoice](https://light.inc/docs/api-reference/v1--invoice-receivables/reset-invoice): `POST /v1/invoice-receivables/{invoiceReceivableId}/reset` — Resets an invoice receivable to draft
  - NOTE: Only from OPEN . A PARTIALLY_PAID or PAID invoice cannot be reset until every clearing is reversed, and an invoice already sent to the customer is locked in countries where Light enforces invoice immutability ( INVOICE_RECEIVABLE_LOCKED ; use reverse and reissue instead). Reset reverses the ledger posting and returns the invoice to DRAFT , but keeps the invoice number : reopening reuses it.
- [Reverse invoice payment](https://light.inc/docs/api-reference/v1--invoice-receivables/reverse-invoice-payment): `POST /v1/invoice-receivables/{invoiceReceivableId}/reverse-clearing` — Reverses a clearing applied to an invoice receivable — either a bank payment ( BP ) or a customer credit ( CC ) — identified by its accounting document ID. Use the List invoice payments endpoint to obtain the accountingDocumentId and type of the clearing to reverse. Reversing removes the clearing's effect from the ledger and transitions the invoice back to OPEN or PARTIALLY_PAID depending on the remaining outstanding balance. Optionally set shouldArchiveClearingDocument to also archive the underlying bank payment or customer credit.
  - NOTE: Only from PARTIALLY_PAID or PAID ; on an OPEN invoice it fails with INVOICE_RECEIVABLE_INVALID_STATE_TRANSITION . accountingDocumentId is the payment.accountingDocumentId from GET .../payments . The resulting state follows what is still cleared: PARTIALLY_PAID if anything remains, else OPEN . With shouldArchiveClearingDocument: true the bank payment or credit is archived; with false a customer credit returns to POSTED and stays linked.
- [Send invoice email](https://light.inc/docs/api-reference/v1--invoice-receivables/send-invoice-email): `POST /v1/invoice-receivables/{invoiceReceivableId}/send-email` — Sends an invoice receivable email with the given email information
  - NOTE: Only for an opened invoice ( OPEN , PARTIALLY_PAID , PAYMENT_PENDING , PAID ); otherwise INVOICE_RECEIVABLE_EMAIL_INVALID_STATE . The email is queued , so a 2xx means accepted, not delivered, and a delivery failure is not reported back. recipients must be non-empty and valid, and subject and customMessage may not contain HTML ( INVOICE_RECEIVABLE_HTML_NOT_ALLOWED ). Returns an empty body.
- [Unarchive invoice](https://light.inc/docs/api-reference/v1--invoice-receivables/unarchive-invoice): `POST /v1/invoice-receivables/{invoiceReceivableId}/unarchive` — Unarchives an invoice receivable and reverts it to draft
  - NOTE: Only from ARCHIVED ( INVOICE_RECEIVABLE_CANNOT_BE_UNARCHIVED ). Always lands in DRAFT , even if the invoice was OPEN when archived; open it again to post. Blocked with INVOICE_RECEIVABLE_LOCKED where invoice immutability applies.

### Journal Entries
Create journal entries programmatically.

- [Archive journal entry](https://light.inc/docs/api-reference/v1--journal-entries/archive-journal-entry): `POST /v1/journal-entries/{journalEntryId}/archive` — Archives the given journal entry. Drafts are archived directly; posted entries are reversed and marked as archived.
  - NOTE: Only a DRAFT or an entry whose status is exactly POSTED can be archived; PARTIALLY_CLEARED , CLEARED , APPROVAL_PENDING and ARCHIVED fail with JOURNAL_ENTRY_CANNOT_BE_ARCHIVED . The reversal of a posted entry is written synchronously with the original postingDate , not today's, so that period must still be open ( ACCOUNTING_PERIOD_CLOSED ). Both the original and the reversing lines then appear on GET /v1/ledger-transaction-lines . A second archive without an X-Idempotency-Key fails rather than no-ops. Periods and locks (/docs/concepts/periods-and-locks) explains the period check.
- [Create journal entry](https://light.inc/docs/api-reference/v1--journal-entries/create-journal-entry): `POST /v1/journal-entries` — Creates a new journal entry
  - NOTE: This is the only way to post a journal entry through the API. There is no endpoint to post an existing draft, to add or change lines, or to read an entry back; a draft can only be archived. Create it with shouldPost: true when it must reach the ledger. If the company has a journal-entry approval workflow, shouldPost: true leaves it in APPROVAL_PENDING for approval in Light instead of POSTED . To read it back later: the header via GET /v1/accounting-documents/accounting-documents?filter=id:eq:{journalEntryId} , the posted lines via GET /v1/ledger-transaction-lines?filter=accDocId:eq:{journalEntryId} ; draft lines are not readable anywhere. Rules enforced only when posting: the lines' grossTransactionAmount in the transaction currency must net to zero ( ACCOUNTING_DOCUMENT_LINES_DEBITS_AND_CREDITS_NOT_ZERO_SUM ), with at least two lines and both a D and a C ( ACCOUNTING_DOCUMENT_TOO_FEW_LINES , ACCOUNTING_DOCUMENT_LINES_NO_CREDIT_AND_DEBIT ); every line needs ledgerAccountId and the header currency and companyEntityId ; the accounting period of postingDate must be open ( ACCOUNTING_PERIOD_CLOSED ). areLinesWithTax decides which amount each line carries: false (the default) takes netTransactionAmount and rejects a gross amount ( ACCOUNTING_DOCUMENT_LINE_GROSS_AMOUNT_SET ), true the reverse. Amounts are unsigned with dcSign ; a negative amount is ACCOUNTING_DOCUMENT_LINE_NEGATIVE_AMOUNT . Defaults: postingDate today, ledgerName PRIMARY ; currency has no default. Send an X-Idempotency-Key : without one every retry creates another entry; with one, a different body is 409 IDEMPOTENCY_VIOLATION . How Light records money (/docs/concepts/how-light-records-money) explains why the lines must balance, Document lifecycle (/docs/concepts/document-lifecycle) what the statuses mean, and Periods and locks (/docs/concepts/periods-and-locks) why a period can reject the posting.
- [List journal entry activity events](https://light.inc/docs/api-reference/v1--journal-entries/list-journal-entry-activity-events): `GET /v1/journal-entries/{journalEntryId}/activity-events` — The journal entry's activity timeline, newest first: who did what to it, when, and which fields changed. Requires permission to view this journal entry. The entityId and entityType filters are fixed by the path here; passing them can only narrow the result.
- [Update journal entry](https://light.inc/docs/api-reference/v1--journal-entries/update-journal-entry): `PATCH /v1/journal-entries/{journalEntryId}` — Updates the given draft journal entry. Only the fields present in the request body are modified; fields set explicitly to null are cleared.
  - NOTE: The "null clears" rule in the description holds for valuationDate , documentNumber , description , currency , businessPartnerName , businessPartnerId and the FX overrides only; companyEntityId , ledgerName , postingDate , documentDate , areLinesWithTax and customProperties cannot be cleared. Lines cannot be changed at all (there is no lines field). On anything but a DRAFT , only customProperties may change; sending any other field fails with JOURNAL_ENTRY_CANNOT_BE_MODIFIED .

### Ledger accounts
List the chart of accounts.

- [List ledger accounts](https://light.inc/docs/api-reference/v1--ledger-accounts/list-ledger-accounts): `GET /v1/ledger-accounts` — Returns a paginated list of ledger accounts
  - NOTE: A hidden filter restricts the list to category: STANDARD_ACCOUNT : header and sum accounts are never returned, and asking for them yields an empty page. ledgerFeature values INVOICE_PAYABLES , CARD_TRANSACTIONS , PURCHASE_ORDERS and REIMBURSEMENTS also restrict to accounts synced from an external accounting system; ALL , INVOICE_RECEIVABLES and JOURNAL_ENTRIES add nothing. Default order is code:asc , and includeCustomProperties defaults to false (the opposite of GET /v1/ledger-transaction-lines ).

### Ledger Transactions
Query ledger transaction lines.

- [List ledger transaction lines](https://light.inc/docs/api-reference/v1--ledger-transactions/list-ledger-transaction-lines): `GET /v1/ledger-transaction-lines` — Returns a paginated list of ledger transaction lines
  - NOTE: Signed amounts on these lines are credit-positive : signedLocalAmount , signedGroupAmount and signedTransactionAmount are negative for a debit and positive for a credit. That is the opposite polarity to the debit-positive balances GET /v1/general-ledger-summary and GET /v1/bank-accounts/{bankAccountId}/balance return, so reconciling one against the other means flipping the sign on one side. dcSign , debit and credit are returned too and say the same thing. Reversal lines are included and cannot be told apart: archiving a posted document leaves the original lines and negated reversing lines with the same accountingDocumentId and postingDate , netting to zero. includeCustomProperties defaults to true . includeMaxLineAmount reports the largest transactionAmount across the whole filtered set, not the page. postingDate is the ledger date; valuationDate is the date whose FX rate produced the local and group amounts, equal to postingDate unless the document overrides it. Default order is newest line first. limit above 200 fails with INVALID_LIMIT_SIZE unless Light has raised the cap for your company, and then only with a single postingDate sort. How Light records money (/docs/concepts/how-light-records-money) explains what these lines are, and Reading amounts (/docs/concepts/reading-amounts) the sign and currency rules.

### Products
Products are goods or services that a company offers to its customers. They can be used on invoices and contracts.

- [Archive product](https://light.inc/docs/api-reference/v1--products/archive-product): `POST /v1/products/{productId}/archive` — Archive the given product
  - NOTE: Idempotent, but refused for one-off products with PRODUCT_IS_ONE_OFF . Contrary to the description, nothing stops an archived product being used on new invoice or contract lines; the only effect is state: ARCHIVED , which hides it in the app. There is no unarchive endpoint.
- [List products](https://light.inc/docs/api-reference/v1--products/list-products): `GET /v1/products` — Returns a list of products
  - NOTE: Default order is createdAt:desc . The list also includes one-off products created from invoice lines (those with an invoiceReceivableId ), and there is no way to filter them out because is_null is not a filter operator.
- [Create product](https://light.inc/docs/api-reference/v1--products/create-product): `POST /v1/products` — Creates a new product
  - NOTE: name must be unique among catalogue products of the company, case-sensitively, and an archived product still holds its name ( PRODUCT_NAME_CONFLICT , returned as 400 ). pricings needs at least one entry and at most one per currency; amounts are in minor units of that currency. defaultTaxId and defaultLedgerAccountId must exist ( PRODUCT_TAX_NOT_FOUND , PRODUCT_LEDGER_ACCOUNT_NOT_FOUND ). The default tax is only applied to invoice lines when Light's own tax engine is in force.
- [Get product](https://light.inc/docs/api-reference/v1--products/get-product): `GET /v1/products/{productId}` — Returns a product by ID
  - NOTE: Any status. An unknown id, or one from another company, is 404 .
- [Update product](https://light.inc/docs/api-reference/v1--products/update-product): `PATCH /v1/products/{productId}` — Updates an existing product
  - NOTE: An ARCHIVED product cannot be updated ( PRODUCT_CANNOT_BE_MODIFIED ), and there is no unarchive endpoint , so archiving is one-way through this API. null clears defaultAvataxCode , defaultTaxId and defaultLedgerAccountId ; name , pricingType , billingRecurrence and pricings cannot be cleared, and pricings replaces the whole list when present.
- [List product activity events](https://light.inc/docs/api-reference/v1--products/list-product-activity-events): `GET /v1/products/{productId}/activity-events` — The product's activity timeline, newest first: who did what to it, when, and which fields changed. Requires permission to view this product. The entityId and entityType filters are fixed by the path here; passing them can only narrow the result.

### Purchase Orders
Create, close, cancel and manage purchase orders and their lines.

- [Batch update purchase order lines](https://light.inc/docs/api-reference/v1--purchase-orders/batch-update-purchase-order-lines): `PUT /v1/purchase-orders/{purchaseOrderId}/lines/bulk` — Updates multiple purchase order line items
  - NOTE: Not a replace-all, and not a merge either. Only the lines whose lineId you list are touched (unknown id: PURCHASE_ORDER_LINE_NOT_RECOGNIZED ; the same id twice: PURCHASE_ORDER_LINE_DUPLICATE_UPDATE ), but for each listed line every scalar field is overwritten with what you send , so an omitted description , costCenterId , accountId , taxCodeId , quantity or unitPrice becomes null . customProperties is the one field null leaves unchanged. The single-line PATCH uses the usual omit-to-keep rule instead.
- [Bulk create purchase order lines](https://light.inc/docs/api-reference/v1--purchase-orders/bulk-create-purchase-order-lines): `POST /v1/purchase-orders/{purchaseOrderId}/lines/bulk` — Creates multiple purchase order line items
  - NOTE: Same rules as the single create; an empty list returns [] and changes nothing.
- [Cancel purchase order](https://light.inc/docs/api-reference/v1--purchase-orders/cancel-purchase-order): `POST /v1/purchase-orders/{purchaseOrderId}/cancel` — Cancels a purchase order
  - NOTE: From IN_DRAFT or APPROVED_ACCOUNTING_ENTRY_PENDING the order is cancelled immediately; from OPEN it goes through CANCEL_PENDING and is cancelled in the background. Blocked while any live bill is matched to the order ( PURCHASE_ORDER_CANCELLATION_BLOCKED_BY_MATCHED_BILL ); unmatch in Light first. Cancelling also cancels the purchase request it came from.
- [Close purchase order](https://light.inc/docs/api-reference/v1--purchase-orders/close-purchase-order): `POST /v1/purchase-orders/{purchaseOrderId}/close` — Closes a purchase order
  - NOTE: Only from OPEN , giving CLOSE_PENDING (with closedAt set) and then CLOSED in the background. Matched bills are not affected. A bill's submit-for-approval with closePurchaseOrder: true closes the matched order the same way.
- [List purchase orders](https://light.inc/docs/api-reference/v1--purchase-orders/list-purchase-orders): `GET /v1/purchase-orders` — Returns a paginated list of purchase orders
  - NOTE: Guarded by the create permission (company-admin or AP-preparation roles), so a purchase-requester or auditor who can read a single order gets 403 on the list. List rows are a different shape from the single read: they add vendorName , ownerName , totalMatchedAmount and line labels, and lack editStatus and customProperties . No searchTerm .
- [Create purchase order](https://light.inc/docs/api-reference/v1--purchase-orders/create-purchase-order): `POST /v1/purchase-orders` — Creates a new purchase order
  - NOTE: Nothing is required at creation — vendor, entity, owner and even lines may be empty; everything is checked at lock . At most 500 lines ( PURCHASE_ORDER_LINES_COUNT_EXCEEDED ). unitPrice is net; per-line taxAmount is computed from taxCodeId only once the order has a companyEntityId , and cannot be overridden. Most response fields marked required below are null on a fresh draft. States: IN_DRAFT → lock → APPROVED_ACCOUNTING_ENTRY_PENDING → OPEN (in the background, when the ERP confirms; erpNumber and documentKey appear then) → close → CLOSE_PENDING → CLOSED , or cancel → CANCEL_PENDING → CANCELLED , or reset → RESET_PENDING → IN_DRAFT . A wrong-state call fails with PURCHASE_ORDER_INVALID_STATE_TRANSITION .
- [Create purchase order line](https://light.inc/docs/api-reference/v1--purchase-orders/create-purchase-order-line): `POST /v1/purchase-orders/{purchaseOrderId}/lines` — Creates a new purchase order line item
  - NOTE: Only while the order is unlocked ( PURCHASE_ORDER_LOCKED ) and not core-locked ( PURCHASE_ORDER_CORE_EDITS_LOCKED ). Tax is computed only when the order has an entity.
- [Get purchase order](https://light.inc/docs/api-reference/v1--purchase-orders/get-purchase-order): `GET /v1/purchase-orders/{purchaseOrderId}` — Returns a purchase order by ID
  - NOTE: Any state, with lines. An unknown id, or one from another company, is 404 .
- [Update purchase order](https://light.inc/docs/api-reference/v1--purchase-orders/update-purchase-order): `PATCH /v1/purchase-orders/{purchaseOrderId}` — Updates an existing purchase order
  - NOTE: Only while unlocked, which in practice means IN_DRAFT ; every other state fails with PURCHASE_ORDER_LOCKED . An order created from an approved purchase request is CORE_EDITS_LOCKED even as a draft: vendorId , companyEntityId and currency cannot change and lines cannot be added or removed ( PURCHASE_ORDER_CORE_EDITS_LOCKED , with forbiddenFields in the context). Fields follow the omit-to-keep, null -to-clear rule. Changing vendorId deletes every bill matching on the order; changing currency recomputes them.
- [List purchase order activity events](https://light.inc/docs/api-reference/v1--purchase-orders/list-purchase-order-activity-events): `GET /v1/purchase-orders/{purchaseOrderId}/activity-events` — The purchase order's activity timeline, newest first: who did what to it, when, and which fields changed. Requires permission to view this purchase order. The entityId and entityType filters are fixed by the path here; passing them can only narrow the result.
- [Lock purchase order](https://light.inc/docs/api-reference/v1--purchase-orders/lock-purchase-order): `POST /v1/purchase-orders/{purchaseOrderId}/lock` — Locks a purchase order to prevent modifications
  - NOTE: Lock is the approval step. It requires companyEntityId , currency , ownerId and vendorId ( PURCHASE_ORDER_HEADER_MISSING_FIELD ), a vendor enabled for that entity, at least one line ( PURCHASE_ORDER_EMPTY_LINES ), each with description , accountId , taxCodeId , quantity and unitPrice ( PURCHASE_ORDER_LINE_MISSING_FIELD ), and required custom properties. The response is APPROVED_ACCOUNTING_ENTRY_PENDING ; the order becomes OPEN , gets its erpNumber and PDF, and the vendor is notified only after the ERP confirms in the background. A failure there leaves it pending with failureContext set. Poll GET .
- [Delete purchase order line](https://light.inc/docs/api-reference/v1--purchase-orders/delete-purchase-order-line): `DELETE /v1/purchase-orders/{purchaseOrderId}/lines/{lineId}` — Deletes a purchase order line item
  - NOTE: Only while unlocked and not core-locked; the last line cannot be deleted ( PURCHASE_ORDER_AT_LEAST_ONE_LINE ). Answers 204 with no body.
- [Update purchase order line](https://light.inc/docs/api-reference/v1--purchase-orders/update-purchase-order-line): `PATCH /v1/purchase-orders/{purchaseOrderId}/lines/{lineId}` — Updates a purchase order line item
  - NOTE: Omit a field to keep it, send null to clear it ( customProperties : null keeps). Only while the order is unlocked ( PURCHASE_ORDER_LOCKED ); on a core-locked order quantity and unitPrice cannot change. Tax is recomputed only when unitPrice or taxCodeId is in the request.
- [Reset purchase order](https://light.inc/docs/api-reference/v1--purchase-orders/reset-purchase-order): `POST /v1/purchase-orders/{purchaseOrderId}/reset` — Resets a purchase order to its initial state
  - NOTE: From OPEN it goes through RESET_PENDING and returns to IN_DRAFT in the background, unlocked, with the ERP entry deleted and the PDF cleared; from APPROVED_ACCOUNTING_ENTRY_PENDING it returns immediately; on a draft it is a no-op. Not allowed from CLOSED or CANCELLED .

### Reimbursement categories
List the reimbursement categories that decide the GL account and tax code on a reimbursement.

- [List reimbursement categories](https://light.inc/docs/api-reference/v1--reimbursement-categories/list-reimbursement-categories): `GET /v1/reimbursement-categories` — Returns a paginated list of the company's reimbursement categories. Every expense line needs one: the category decides the GL account and tax code its reimbursement books to.
  - NOTE: entityIds is optional and an empty value means no entity filter. Because an expense line's category must belong to the user's own entity, pass that user's companyEntityId to get the categories you can actually use. Default order is label:asc ; searchTerm matches label case-insensitively.

### User Comments
Create, list and manage comments on records.

- [List user comments](https://light.inc/docs/api-reference/v1--user-comments/list-user-comments): `GET /v1/user-comments` — List user comments for a given resource
  - NOTE: resourceId is required. Comments come back newest first by default; createdAt is the only sortable field.
- [Create user comment](https://light.inc/docs/api-reference/v1--user-comments/create-user-comment): `POST /v1/user-comments` — Creates a new user comment
  - NOTE: resourceId is the id of the record being commented on (any record type; there is no resourceType ), and it is not validated — a wrong id is accepted silently. content is stored and returned verbatim with no length limit and no mention syntax. createdBy is always the caller; for an API key that is the key's service-account id.
- [Delete user comment](https://light.inc/docs/api-reference/v1--user-comments/delete-user-comment): `DELETE /v1/user-comments/{userCommentId}` — Deletes the given user comment
  - NOTE: Author-only ( 403 for anyone else, 404 USER_COMMENT_NOT_FOUND if unknown). The delete is permanent and answers 204 with no body.
- [Update user comment](https://light.inc/docs/api-reference/v1--user-comments/update-user-comment): `PATCH /v1/user-comments/{userCommentId}` — Updates the given user comment
  - NOTE: Author-only: a comment created by another user (or another API key) fails with 403 ; an unknown id with 404 USER_COMMENT_NOT_FOUND . content is required and replaces the text entirely.

### Users
List users and manage their reimbursement configuration.

- [List users](https://light.inc/docs/api-reference/v1--users/list-users): `GET /v1/users` — Returns a paginated list of users
  - NOTE: Deactivated users are hidden unless you filter on status yourself (for example status:eq:DEACTIVATED ). roles , groups and managerIds are null unless includeRoles , includeGroups or includeManagers is true . The role filter matches through the role hierarchy; assignedRole matches only roles assigned directly.
- [Create user](https://light.inc/docs/api-reference/v1--users/create-user): `POST /v1/users` — Creates a new user
  - NOTE: The user is created ACTIVE straight away; no acceptance step. A welcome email goes out when sendWelcomeEmail is true , or when it is omitted and the company setting to send them is on; false suppresses it. email must be unique across Light ( USER_ALREADY_REGISTERED ). roles is required; Light-internal roles such as SUPERUSER are rejected with USER_HAS_ILLEGAL_ROLE even though the enum lists them. Company-admin role only.
- [Get latest reimbursement](https://light.inc/docs/api-reference/v1--users/get-latest-reimbursement): `GET /v1/users/{userId}/reimbursements/latest` — Returns the most recent reimbursement for a user
  - NOTE: The most recently created reimbursement for the user, i.e. the result of their last POST /v1/expenses/submit . status is IN_PROGRESS after submission, then SUCCEEDED when paid, REJECTED when an administrator rejects it, or FAILED when the submission workflow failed (its expenses return to IN_DRAFT ). A user who never submitted is 404 REIMBURSEMENTS_NOT_FOUND_FOR_USER .
- [Get reimbursement config](https://light.inc/docs/api-reference/v1--users/get-reimbursement-config): `GET /v1/users/{userId}/reimbursement-config` — Returns the reimbursement configuration for a user
  - NOTE: 404 USER_REIMBURSEMENT_CONFIG_NOT_FOUND until one has been created with the PUT .
- [Update reimbursement config](https://light.inc/docs/api-reference/v1--users/update-reimbursement-config): `PUT /v1/users/{userId}/reimbursement-config` — Creates or updates the reimbursement configuration for a user
  - NOTE: bankCountry is required. status is always ACTIVE and cannot be set. Bank details are not validated here; they are checked when the user submits ( USER_INVALID_BANK_DETAILS ). defaultCostCenterId becomes the cost centre of every expense line the user creates through the API. Changing currency rewrites the billing currency of all of the user's unsubmitted expenses and recalculates their line amounts. Company-admin role, or the user themself with the reimbursement role.
- [Update user](https://light.inc/docs/api-reference/v1--users/update-user): `PATCH /v1/users/{userId}` — Updates the given user
  - NOTE: Two kinds of field. firstName , lastName , email and companyEntityId cannot be cleared: null leaves them unchanged. phoneNumber , avatarUrl , country , city , address and zipcode follow the usual rule ( null clears). A credential without the company-admin role may only update its own user and cannot change email . A new email already in use fails with USER_ALREADY_REGISTERED .
- [Update user managers](https://light.inc/docs/api-reference/v1--users/update-user-managers): `PUT /v1/users/{userId}/managers` — Updates the given user's managers
  - NOTE: A full replacement: the list you send becomes the manager list, and [] clears it. At most five managers ( USER_HAS_TOO_MANY_MANAGERS ), each an active user of the company other than the user themself ( USER_HAS_INVALID_MANAGER ). Company-admin role only.
- [Update user status](https://light.inc/docs/api-reference/v1--users/update-user-status): `PUT /v1/users/{userId}/status` — Updates the given user's status
  - NOTE: ACTIVE or DEACTIVATED , in either direction; setting the current status again is a no-op. You cannot change the status of the credential's own user ( USER_SELF_STATUS_UPDATE ). Deactivating a user freezes every card they own , drops them from GET /v1/users by default, and makes them ineligible as a card owner or manager.

### Vendors
Create, list, update and manage vendors.

- [List vendors](https://light.inc/docs/api-reference/v1--vendors/list-vendors): `GET /v1/vendors` — Returns a paginated list of vendors
  - NOTE: Without a filter , only active external vendors are returned (the default is status:eq:ACTIVE,type:eq:EXTERNAL ). Any filter you send replaces that default , so filter=id:eq:... also returns IN_REVIEW , ONBOARDING , FAILED and employee ( USER ) vendors. Default order is name:asc ; searchTerm is supported. lastMtdSpendInGroupCurrency and groupCurrency are populated only here, never on the create, update or single-read responses; notes is always [] .
- [Create vendor](https://light.inc/docs/api-reference/v1--vendors/create-vendor): `POST /v1/vendors` — Creates a new vendor
  - NOTE: The resulting status depends on the company's vendor-approval workflow: with one published the vendor is created IN_REVIEW and must be approved in Light before it can be updated ( VENDOR_PENDING_APPROVAL_UPDATE_NOT_ALLOWED ); otherwise it is ACTIVE . Uniqueness is on name only ( DUPLICATE_VENDOR ); VAT id, IBAN and identifier may repeat. Bank details are validated by country (IBAN/BIC or domestic formats, errors pathed to the field); French vendors get their VAT number and SIREN cross-checked ( VENDOR_INVALID_FRENCH_IDENTIFIERS ). Missing contact fields ( description , email , phoneNumber , address , ...) are back-filled from a lookup of website when given. type is always EXTERNAL ; defaultCompanyEntity.companyEntityId is added to companyEntityIds automatically. Requires the vendor-management role.
- [Get vendor](https://light.inc/docs/api-reference/v1--vendors/get-vendor): `GET /v1/vendors/{vendorId}` — Returns a vendor by ID
  - NOTE: Any status, IN_REVIEW , ONBOARDING and FAILED included. Readable with any of the vendor-management, AP preparation, invoice approver, cardholder, purchase requester or auditor roles.
- [Update vendor](https://light.inc/docs/api-reference/v1--vendors/update-vendor): `PUT /v1/vendors/{vendorId}` — Updates an existing vendor
  - NOTE: A full replacement : every field you omit or send as null is cleared ( vatId , identifier , defaultCompanyEntity , all bank fields, ...), and companyEntityIds is replaced. Two exceptions: the web-enrichable contact fields fall back to the website lookup, and a null customProperties keeps the existing set. Send the full current record with your change applied. status cannot be set and there is no archive or delete endpoint . Values: ONBOARDING , IN_REVIEW , ACTIVE , FAILED (rejected). An IN_REVIEW vendor cannot be updated ( VENDOR_PENDING_APPROVAL_UPDATE_NOT_ALLOWED ); updating a FAILED one re-submits it for review. When a vendor-approval workflow is published, bank-detail changes on an active vendor are not applied : they are parked as a change request until approved in Light, and a second change meanwhile fails with VENDOR_BANK_DATA_APPROVAL_ALREADY_IN_PROGRESS ; other fields apply immediately. Companies on an external ledger cannot rename a vendor ( FIELD_UPDATE_NOT_SUPPORTED_IN_EXTERNAL_LEDGER ).
- [List vendor activity events](https://light.inc/docs/api-reference/v1--vendors/list-vendor-activity-events): `GET /v1/vendors/{vendorId}/activity-events` — The vendor's activity timeline, newest first: who did what to it, when, and which fields changed. Requires permission to view this vendor. The entityId and entityType filters are fixed by the path here; passing them can only narrow the result.
- [Trigger vendor onboarding](https://light.inc/docs/api-reference/v1--vendors/trigger-vendor-onboarding): `POST /v1/vendors/{vendorId}/trigger-onboarding` — Resends the self-service onboarding magic-link email for a vendor that already has an onboarding form