Light v1 - Invoice Receivables API
The v1 - Invoice Receivables API from Light — 11 operation(s) for v1 - invoice receivables.
OpenAPI Specification
openapi: 3.0.1
info:
title: Light Authorization v1 - Invoice Receivables API
version: 1.0.0
security:
- apiKeyAuth: []
- bearerAuth: []
tags:
- name: v1 - Invoice Receivables
paths:
/v1/invoice-receivables/{invoiceReceivableId}/archive:
post:
tags:
- v1 - Invoice Receivables
summary: Archive invoice
description: Archives an invoice receivable
operationId: archiveInvoiceReceivable
parameters:
- name: invoiceReceivableId
in: path
required: true
schema:
type: string
format: uuid
responses:
default:
description: default response
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalInvoiceReceivableV1Model'
/v1/invoice-receivables:
get:
tags:
- v1 - Invoice Receivables
summary: List invoices
description: Returns a paginated list of invoice receivables
operationId: listInvoiceReceivables
parameters:
- name: sort
in: query
schema:
type: string
description: "Sort string in the format `field:direction`. To provide multiple sort fields, separate them with commas.\n\nAvailable directions: `asc`, `desc`. \n\nAvailable fields: `amount`, `companyEntityId`, `createdAt`, `customer`, `description`, `dueDate`, `effectiveInvoiceDate`, `invoiceDate`, `invoiceNumber`, `openedAt`, `postingDate`, `state`, `updatedAt`."
example: amount:desc,createdAt:asc
- name: filter
in: query
schema:
type: string
description: "Filter string in the format `field:operator:value`. To provide multiple filters, separate them with commas.\n\nAvailable operators: `eq`, `ne`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`.\n - For `in` and `not_in` operators, provide multiple values separated by the pipe character (`|`). \n\nAvailable fields: `companyEntityId`, `contractId`, `currency`, `customerId`, `invoiceTemplateId`, `payeeBankAccountId`, `paymentType`, `openedAt`, `documentNumber`, `documentStatus`, `dueDate`, `effectiveInvoiceDate`, `einvoiceStatus`, `id`, `invoiceDate`, `postingDate`, `state`, `updatedAt`."
example: state:in:IN_DRAFT|SCHEDULED|PAID,amount:gte:500,vendorId:ne:null
- name: limit
in: query
description: Maximum number of items to return. Default is 50, maximum is 200.
schema:
maximum: 200
type: integer
format: int32
- name: offset
in: query
description: Number of items to skip before starting to collect the result set. Deprecated, use 'cursor' instead.
deprecated: true
schema:
type: integer
format: int64
- name: cursor
in: query
description: 'The cursor position to start returning results from.
To opt-in into cursor-based pagination, provide `0` for the initial request.
For subsequent requests, use `nextCursor` and `prevCursor` from the previous response to navigate.
Cursor values are opaque and should not be constructed manually.'
schema:
type: string
responses:
default:
description: default response
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalPaginatedResponseV1ModelExternalInvoiceReceivableV1Model'
post:
tags:
- v1 - Invoice Receivables
summary: Create invoice
description: Creates a new sales invoice
operationId: createInvoice
parameters:
- name: X-Idempotency-Key
in: header
schema:
type: string
requestBody:
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalCreateInvoiceReceivableRequestV1Model'
responses:
default:
description: default response
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalInvoiceReceivableV1Model'
/v1/invoice-receivables/{invoiceReceivableId}/lines:
post:
tags:
- v1 - Invoice Receivables
summary: Create line
description: Creates a new invoice line item
operationId: createInvoiceLine
parameters:
- name: invoiceReceivableId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalCreateInvoiceReceivableLineRequestV1Model'
responses:
default:
description: default response
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalInvoiceReceivableLineV1Model'
/v1/invoice-receivables/{invoiceReceivableId}/lines/{lineId}:
delete:
tags:
- v1 - Invoice Receivables
summary: Delete invoice line
description: Deletes an invoice line item
operationId: deleteInvoiceLine
parameters:
- name: invoiceReceivableId
in: path
required: true
schema:
type: string
format: uuid
- name: lineId
in: path
required: true
schema:
type: string
format: uuid
responses:
default:
description: default response
content:
application/json;charset=UTF-8: {}
patch:
tags:
- v1 - Invoice Receivables
summary: Update invoice line
description: Updates an invoice line item
operationId: updateInvoiceLine
parameters:
- name: invoiceReceivableId
in: path
required: true
schema:
type: string
format: uuid
- name: lineId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalUpdateInvoiceReceivableLineRequestV1Model'
responses:
default:
description: default response
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalInvoiceReceivableLineV1Model'
/v1/invoice-receivables/{invoiceReceivableId}/document:
post:
tags:
- v1 - Invoice Receivables
summary: Generate invoice PDF
description: 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.
operationId: generateInvoiceReceivableDocument
parameters:
- name: invoiceReceivableId
in: path
required: true
schema:
type: string
format: uuid
responses:
default:
description: default response
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalInvoiceReceivablePdfDocumentV1Model'
/v1/invoice-receivables/{invoiceReceivableId}:
get:
tags:
- v1 - Invoice Receivables
summary: Get invoice
description: Returns a specific invoice receivable by ID
operationId: getInvoiceReceivable
parameters:
- name: invoiceReceivableId
in: path
required: true
schema:
type: string
format: uuid
responses:
default:
description: default response
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalInvoiceReceivableV1Model'
patch:
tags:
- v1 - Invoice Receivables
summary: Update invoice
description: Updates an invoice receivable
operationId: updateInvoiceReceivable
parameters:
- name: invoiceReceivableId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalUpdateInvoiceReceivableRequestV1Model'
responses:
default:
description: default response
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalInvoiceReceivableV1Model'
/v1/invoice-receivables/{invoiceReceivableId}/payments:
get:
tags:
- v1 - Invoice Receivables
summary: List invoice payments
description: Returns a list of payments for an invoice receivable
operationId: listInvoiceReceivablePayments
parameters:
- name: invoiceReceivableId
in: path
required: true
schema:
type: string
format: uuid
responses:
default:
description: default response
content:
application/json;charset=UTF-8:
schema:
type: array
items:
$ref: '#/components/schemas/ExternalInvoiceReceivablePaymentV1Model'
post:
tags:
- v1 - Invoice Receivables
summary: Enter invoice payment
description: 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.
operationId: recordInvoicePayment
parameters:
- name: invoiceReceivableId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalRegisterInvoiceReceivablePaymentRequestV1Model'
responses:
default:
description: default response
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalInvoiceReceivableV1Model'
/v1/invoice-receivables/{invoiceReceivableId}/open:
post:
tags:
- v1 - Invoice Receivables
summary: Open invoice
description: 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).
operationId: openInvoiceReceivable
parameters:
- name: invoiceReceivableId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
description: Optional configuration for opening the invoice. If not provided, invoice will be opened with default settings (no email, no e-invoice).
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalInitInvoiceReceivableOpenRequestV1Model'
responses:
'200':
description: 'Invoice open process initiated successfully. The invoice status will change to `OPEN_IN_PROGRESS`. You must poll the invoice to check when it changes to `OPEN`.
If the invoice fails to open, the status will change back to `DRAFT` and the `failureContext` field will be populated with the error details.'
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalInvoiceReceivableV1Model'
/v1/invoice-receivables/{invoiceReceivableId}/reset:
post:
tags:
- v1 - Invoice Receivables
summary: Reset invoice
description: Resets an invoice receivable to draft
operationId: resetInvoiceReceivable
parameters:
- name: invoiceReceivableId
in: path
required: true
schema:
type: string
format: uuid
responses:
default:
description: default response
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalInvoiceReceivableV1Model'
/v1/invoice-receivables/{invoiceReceivableId}/send-email:
post:
tags:
- v1 - Invoice Receivables
summary: Send invoice email
description: Sends an invoice receivable email with the given email information
operationId: sendInvoiceReceivableEmail
parameters:
- name: invoiceReceivableId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalInvoiceReceivableEmailInfoRequestV1Model'
responses:
default:
description: default response
content:
application/json;charset=UTF-8: {}
/v1/invoice-receivables/{invoiceReceivableId}/unarchive:
post:
tags:
- v1 - Invoice Receivables
summary: Unarchive invoice
description: Unarchives an invoice receivable and reverts it to draft
operationId: unarchiveInvoiceReceivable
parameters:
- name: invoiceReceivableId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Invoice receivable unarchived successfully.
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalInvoiceReceivableV1Model'
'400':
description: Bad request. Invoice receivable is not archived.
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ExternalUiClientExceptionV1Model'
components:
schemas:
ExternalCreateInvoiceReceivableRequestV1Model:
type: object
properties:
companyEntityId:
type: string
description: ID of the company entity
format: uuid
invoiceNumber:
type: string
description: Unique invoice number. If not provided, one will be generated automatically when the invoice is opened.
nullable: true
description:
type: string
description: Invoice description
nullable: true
currency:
type: string
nullable: true
example: USD
paymentType:
type: string
description: 'Payment type for the invoice
- `AIRWALLEX` - Payment via Airwallex. A payment link will be displayed on the invoice
- `BANK_TRANSFER` - Payment via bank transfer. Bank information will be displayed on the invoice
- `DIRECT_DEBIT` - Payment via direct debit. A notice that the amount will be collected automatically will be displayed on the invoice
- `STRIPE` - Payment via Stripe. A payment link will be sent to the customer
⚠️ This enum is not exhaustive; new values may be added in the future.'
nullable: true
deprecated: false
enum:
- AIRWALLEX
- BANK_TRANSFER
- DIRECT_DEBIT
- STRIPE
payeeBankAccountId:
type: string
description: ID of the bank account where money should be sent to
format: uuid
nullable: true
invoiceDate:
type: string
description: Date the invoice was issued
format: date
nullable: true
postingDate:
type: string
description: Date the invoice is posted to the ledger (drives GL, VAT and revenue recognition). Defaults to the invoice date when omitted.
format: date
nullable: true
dueDate:
type: string
description: Date the invoice payment is due
format: date
nullable: true
customerId:
type: string
description: ID of the customer
format: uuid
nullable: true
invoiceTemplateId:
type: string
description: ID of the invoice template
format: uuid
nullable: true
netTerms:
type: integer
description: Number of days from the invoice date to when the invoice is due. Setting this will automatically calculate the due date
format: int32
nullable: true
poNumber:
type: string
description: Purchase order number
nullable: true
reference:
type: string
description: Reference number for cross-referencing with procurement and invoicing workflows
nullable: true
invoiceTemplateAdditionalText:
type: string
description: Text that will be added to the additional text section of the invoice template
nullable: true
areLinesWithTax:
type: boolean
description: Whether the invoice line amounts are inclusive of tax. True means tax is included in the line amount, false means tax will be added on top
default: true
localCurrencyFxRate:
type: number
description: Custom foreign exchange rate for the ledger's local currency. If not provided, Light uses official ECB rates
nullable: true
groupCurrencyFxRate:
type: number
description: Custom foreign exchange rate for the ledger's group currency. If not provided, Light uses official ECB rates
nullable: true
lines:
type: array
description: List of invoice line items to create
nullable: true
items:
$ref: '#/components/schemas/ExternalCreateInvoiceReceivableLineRequestV1Model'
customProperties:
type: array
description: List of custom properties to set on the invoice or line
nullable: true
items:
$ref: '#/components/schemas/ExternalSetCustomPropertyRequestV1Model'
ExternalRegisterInvoiceReceivablePaymentRequestV1Model:
type: object
properties:
paymentDate:
type: string
description: Date the payment was made
format: date
bankAccountId:
type: string
description: ID of the bank account the payment was received in
format: uuid
amountInInvoiceCurrency:
type: integer
description: Payment amount in smallest denomination, in the invoice's currency
format: int64
ExternalUpdateInvoiceReceivableRequestV1Model:
type: object
properties:
companyEntityId:
type: string
description: ID of the company entity
format: uuid
nullable: true
currency:
type: string
nullable: true
example: USD
paymentType:
type: string
description: 'Payment type for the invoice
- `AIRWALLEX` - Payment via Airwallex. A payment link will be displayed on the invoice
- `BANK_TRANSFER` - Payment via bank transfer. Bank information will be displayed on the invoice
- `DIRECT_DEBIT` - Payment via direct debit. A notice that the amount will be collected automatically will be displayed on the invoice
- `STRIPE` - Payment via Stripe. A payment link will be sent to the customer
⚠️ This enum is not exhaustive; new values may be added in the future.'
nullable: true
deprecated: false
enum:
- AIRWALLEX
- BANK_TRANSFER
- DIRECT_DEBIT
- STRIPE
invoiceDate:
type: string
description: Date the invoice was issued
format: date
nullable: true
postingDate:
type: string
description: Date the invoice is posted to the ledger (drives GL, VAT and revenue recognition). Defaults to the invoice date when omitted.
format: date
nullable: true
dueDate:
type: string
description: Date the invoice payment is due
format: date
nullable: true
customerId:
type: string
description: ID of the customer
format: uuid
nullable: true
areLinesWithTax:
type: boolean
description: Whether the invoice line amounts are inclusive of tax. True means tax is included in the line amount, false means tax will be added on top
nullable: true
netTerms:
type: integer
description: Number of days from the invoice date to when the invoice is due. Setting this will automatically calculate the due date
format: int32
nullable: true
invoiceNumber:
type: string
description: Unique invoice number. If not provided, one will be generated automatically when the invoice is opened.
nullable: true
payeeBankAccountId:
type: string
description: ID of the bank account where money should be sent to
format: uuid
nullable: true
invoiceTemplateId:
type: string
description: ID of the invoice template
format: uuid
nullable: true
description:
type: string
description: Invoice description
nullable: true
poNumber:
type: string
description: Purchase order number
nullable: true
reference:
type: string
description: Reference number for cross-referencing with procurement and invoicing workflows
nullable: true
invoiceTemplateAdditionalText:
type: string
description: Text that will be added to the additional text section of the invoice template
nullable: true
customProperties:
type: array
description: List of custom properties to set on the invoice or line
nullable: true
items:
$ref: '#/components/schemas/ExternalSetCustomPropertyRequestV1Model'
ExternalUpdateInvoiceReceivableLineRequestV1Model:
type: object
properties:
productId:
type: string
description: ID of the product
format: uuid
nullable: true
quantity:
type: number
description: Quantity of the product
nullable: true
accountId:
type: string
description: ID of the ledger account for this line
format: uuid
nullable: true
taxCodeId:
type: string
description: ID of the tax code to apply to this line
format: uuid
nullable: true
discount:
$ref: '#/components/schemas/ExternalAccountReceivableLineDiscountV1Model'
priceOverwrite:
type: integer
description: Price overwrite in smallest denomination. If not provided, the product's default price will be used
format: int64
nullable: true
productNameOverwrite:
type: string
description: Product name overwrite. If not provided, the product's default name will be used
nullable: true
taxAmountOverwrite:
type: integer
description: 'Tax amount override in smallest denomination. Bypasses tax calculation and sets the exact tax amount for this line.
Requirements: The line must have a valid amount (product price or priceOverwrite must be set).
The taxAmount field in the response will reflect this override value.
Amounts use smallest denomination. Examples: GBP 42.15 = 4215, JPY 12345 = 12345, BHD 7.321 = 7321.'
format: int64
nullable: true
avataxCode:
type: string
description: Avalara tax code. Used when the invoice tax engine is AVATAX
nullable: true
billingStart:
type: string
description: Start of the billing period for this line
format: date
nullable: true
billingEnd:
type: string
description: End of the billing period for this line
format: date
nullable: true
customProperties:
type: array
description: List of custom properties to set on the invoice or line
nullable: true
items:
$ref: '#/components/schemas/ExternalSetCustomPropertyRequestV1Model'
accrualTemplateId:
type: string
description: ID of the accrual/amortization template to apply to this line
format: uuid
nullable: true
accrualStartDate:
type: string
description: Start date for accrual/amortization
format: date
nullable: true
accrualEndDate:
type: string
description: End date for accrual/amortization
format: date
nullable: true
ExternalInvoiceReceivableLineV1Model:
type: object
properties:
id:
type: string
description: Unique identifier for the object
format: uuid
companyId:
type: string
description: ID of the company
format: uuid
invoiceReceivableId:
type: string
description: ID of the invoice receivable this line belongs to
format: uuid
productId:
type: string
description: ID of the product
format: uuid
quantity:
type: number
description: Quantity of the product
taxCodeId:
type: string
description: ID of the tax code
format: uuid
nullable: true
accountId:
type: string
description: ID of the ledger account
format: uuid
nullable: true
discount:
$ref: '#/components/schemas/ExternalAccountReceivableLineDiscountV1Model'
discountAmount:
type: integer
description: Discount amount in smallest denomination
format: int64
nullable: true
netAmount:
type: integer
description: Net amount in smallest denomination after discount but before tax
format: int64
nullable: true
taxAmount:
type: integer
description: Tax amount in smallest denomination
format: int64
nullable: true
avataxCode:
type: string
description: Avalara tax code. Used when the invoice tax engine is `AVATAX`
nullable: true
billingStart:
type: string
description: Start of the billing period
format: date
nullable: true
billingEnd:
type: string
description: End of the billing period
format: date
nullable: true
priceOverwrite:
type: integer
description: Custom product price in smallest denomination. This overrides the default product's price
format: int64
nullable: true
productNameOverwrite:
type: string
description: Custom product name. This overrides the default product's name
nullable: true
createdAt:
type: string
description: Timestamp when the line was created
format: date-time
updatedAt:
type: string
description: Timestamp when the line was last updated
format: date-time
accrualTemplateId:
type: string
description: ID of the accrual template
format: uuid
nullable: true
accrualStartDate:
type: string
description: Start date for accrual
format: date
nullable: true
accrualEndDate:
type: string
description: End date for accrual
format: date
nullable: true
customProperties:
type: array
description: List of custom properties associated with the line
nullable: true
items:
$ref: '#/components/schemas/ExternalCustomPropertyV1Model'
ExternalInvoiceReceivablePaymentBankPaymentEntryV1Model:
title: Bank payment
type: object
allOf:
- $ref: '#/components/schemas/ExternalInvoiceReceivablePaymentEntryV1Model'
- type: object
properties:
bankAccountId:
type: string
description: ID of the bank account
format: uuid
nullable: true
endToEndId:
type: string
description: End-to-end ID for the payment
nullable: true
originalAmount:
type: integer
description: Original payment amount in smallest denomination
format: int64
originalCurrency:
type: string
example: USD
accountingDocumentId:
type: string
description: ID of the accounting document
format: uuid
ExternalInvoiceReceivablePaymentEntryV1Model:
type: object
properties:
type:
type: string
description: '- `BP` - Bank payment
- `CC` - Customer credit
⚠️ This enum is not exhaustive; new values may be added in the future.'
enum:
- BP
- CC
description: Type of payment entry for an invoice receivable payment
nullable: true
discriminator:
propertyName: type
oneOf:
- $ref: '#/components/schemas/ExternalInvoiceReceivablePaymentBankPaymentEntryV1Model'
- $ref: '#/components/schemas/ExternalInvoiceReceivablePaymentCustomerCreditEntryV1Model'
ExternalSetCustomPropertyRequestV1Model:
type: object
properties:
groupId:
type: string
description: ID of the custom property group.
format: uuid
valueIds:
type: array
description: IDs of the selected custom property values. It behaves as a PUT operation, so if empty the existing ones will be effectively deleted.
items:
type: string
description: IDs of the selected custom property values. It behaves as a PUT operation, so if empty the existing ones will be effectively deleted.
format: uuid
inlineValues:
type: array
description: Inline custom property values (used for TEXT/NUMERIC/DATE/etc. groups). It behaves as a PUT operation, so if empty or null the existing ones will be effectively deleted.
nullable: true
items:
type: string
description: Inline custom property values (used for TEXT/NUMERIC/DATE/etc. groups). It behaves as a PUT operation, so if empty or null the existing ones will be effectively deleted.
nullable: true
description: List of custom properties to set on the vendor. Replaces the existing set.
nullable: true
ExternalInvoiceReceivableV1Model:
type: object
properties:
id:
type: string
description: Unique identifier for the object
format: uuid
companyId:
type: string
description: ID of the company
format: uuid
contractId:
type: string
description: ID of the contract, if this is invoice is linked to a contract
format: uuid
nullable: true
companyEntityId:
type: string
description: ID of the entity
format: uuid
nullable: true
amount:
type: integer
description: Total invoice amount in smallest denomination, with discounts and tax applied
format: int64
paymentType:
type: string
description: 'Payment type for the invoice
- `AIRWALLEX` - Payment via Airwallex. A payment link will be displayed on the invoice
- `BANK_TRANSFER` - Payment via bank transfer. Bank information will be displayed on the invoi
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/light/refs/heads/main/openapi/light-v1-invoice-receivables-api-openapi.yml