---
title: "Create invoice"
method: POST
path: "/v1/invoice-receivables"
tags: ["v1 - Invoice Receivables"]
---

# Create invoice

`POST /v1/invoice-receivables`

## Request

- Base URL: `https://light.inc` (the document declares no server; this is the origin it was published from)
- URL: `https://light.inc/v1/invoice-receivables`
- Auth: one of:
  - API key in header `Authorization`
  - HTTP bearer

Creates a new sales invoice

## Headers

- `X-Idempotency-Key` string

## Request body

- ExternalCreateInvoiceReceivableRequestV1Model
  - `companyEntityId` string, uuid: ID of the company entity
  - `invoiceNumber` string, nullable: Unique invoice number. If not provided, one will be generated automatically when the invoice is opened.
  - `description` string, nullable: Invoice description
  - `currency` string, nullable
  - `paymentType` 'AIRWALLEX' | 'BANK_TRANSFER' | 'DIRECT_DEBIT' | 'STRIPE', nullable: 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.
  - `payeeBankAccountId` string, uuid, nullable: ID of the bank account where money should be sent to
  - `invoiceDate` string, date, nullable: Date the invoice was issued
  - `postingDate` string, date, nullable: Date the invoice is posted to the ledger (drives GL, VAT and revenue recognition). Defaults to the invoice date when omitted.
  - `dueDate` string, date, nullable: Date the invoice payment is due
  - `customerId` string, uuid, nullable: ID of the customer
  - `invoiceTemplateId` string, uuid, nullable: ID of the invoice template
  - `netTerms` integer, nullable: Number of days from the invoice date to when the invoice is due. Setting this will automatically calculate the due date
  - `poNumber` string, nullable: Purchase order number
  - `reference` string, nullable: Reference number for cross-referencing with procurement and invoicing workflows
  - `invoiceTemplateAdditionalText` string, nullable: Text that will be added to the additional text section of the invoice template
  - `areLinesWithTax` boolean: 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
  - `localCurrencyFxRate` number, nullable: Custom foreign exchange rate for the ledger's local currency. If not provided, Light uses official ECB rates
  - `groupCurrencyFxRate` number, nullable: Custom foreign exchange rate for the ledger's group currency. If not provided, Light uses official ECB rates
  - `lines` ExternalCreateInvoiceReceivableLineRequestV1Model[], nullable: List of invoice line items to create
    - `productId` string, uuid: ID of the product
    - `quantity` number: Quantity of the product
    - `taxCodeId` string, uuid, nullable: ID of the tax code to apply to this line
    - `accountId` string, uuid, nullable: ID of the ledger account for this line
    - `discount` ExternalAccountReceivableLineDiscountV1Model, nullable: Discount to apply to this line (can be percentage or amount-based)
      - `type` 'PERCENTAGE' | 'AMOUNT': ⚠️ This enum is not exhaustive; new values may be added in the future.
    - `priceOverwrite` integer, nullable: Price overwrite in smallest denomination. If not provided, the product's default price will be used
    - `productNameOverwrite` string, nullable: Product name overwrite. If not provided, the product's default name will be used
    - `taxAmountOverwrite` integer, nullable: 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.
    - `avataxCode` string, nullable: Avalara tax code. Used when the invoice tax engine is AVATAX
    - `billingStart` string, date, nullable: Start of the billing period for this line
    - `billingEnd` string, date, nullable: End of the billing period for this line
    - `accrualTemplateId` string, uuid, nullable: ID of the accrual/amortization template to apply to this line
    - `accrualStartDate` string, date, nullable: Start date for accrual/amortization
    - `accrualEndDate` string, date, nullable: End date for accrual/amortization
    - `customProperties` ExternalSetCustomPropertyRequestV1Model[], nullable: List of custom properties to set on the invoice or line
      - `groupId` string, uuid: ID of the custom property group.
      - `valueIds` string[]: IDs of the selected custom property values. It behaves as a PUT operation, so if empty the existing ones will be effectively deleted.
      - `inlineValues` string[], nullable: 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.
  - `customProperties` ExternalSetCustomPropertyRequestV1Model[], nullable: List of custom properties to set on the invoice or line
    - `groupId` string, uuid: ID of the custom property group.
    - `valueIds` string[]: IDs of the selected custom property values. It behaves as a PUT operation, so if empty the existing ones will be effectively deleted.
    - `inlineValues` string[], nullable: 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.

## Response `default`

default response

- ExternalInvoiceReceivableV1Model
  - `id` string, uuid: Unique identifier for the object
  - `companyId` string, uuid: ID of the company
  - `contractId` string, uuid, nullable: ID of the contract, if this is invoice is linked to a contract
  - `companyEntityId` string, uuid, nullable: ID of the entity
  - `amount` integer: Total invoice amount in smallest denomination, with discounts and tax applied
  - `paymentType` 'AIRWALLEX' | 'BANK_TRANSFER' | 'DIRECT_DEBIT' | 'STRIPE', nullable: 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.
  - `payeeBankAccountId` string, uuid, nullable: ID of the bank account where money should be sent to
  - `invoiceDate` string, date, nullable: Date the invoice was issued
  - `effectiveInvoiceDate` string, date: The invoice date shown to customers; falls back to the posting date when the invoice date is not set
  - `postingDate` string, date: Date the invoice is posted to the ledger (drives GL, VAT and revenue recognition)
  - `dueDate` string, date, nullable: Date the invoice payment is due
  - `netTerms` integer, nullable: Number of days from the invoice date to when the invoice is due. Updating this field will automatically set the invoice due date
  - `customerId` string, uuid, nullable: ID of the customer
  - `invoiceTemplateId` string, uuid, nullable: ID of the invoice template
  - `invoiceTemplateAdditionalText` string, nullable: Text that will added to the additional text section of the invoice template
  - `invoiceNumber` string, nullable: Invoice number. This number is guaranteed to be unique and sequential per entity. By default Light will generate this number when the invoice is opened, but you can provide your own custom number when creating or updating a draft invoice
  - `type` 'STANDARD' | 'SELF_BILLED': Who raised the invoice - `STANDARD` - The company raised the invoice - `SELF_BILLED` - The customer issued the invoice on the company's behalf and sent it in ⚠️ This enum is not exhaustive; new values may be added in the future.
  - `state` 'CREATED' | 'DRAFT' | 'OPEN_IN_PROGRESS' | 'OPEN' | 'PAYMENT_PENDING' | 'PARTIALLY_PAID' | 'PAID' | 'REVERSED' | 'ARCHIVED': The invoice state - `CREATED` - The invoice document was received and is waiting to be parsed. Next valid state is DRAFT - `DRAFT` - The invoice is in draft and can be modified. Next valid states are OPEN_IN_PROGRESS or ARCHIVED - `OPEN_IN_PROGRESS` - The invoice is being opened. Next valid state is OPEN or DRAFT - `OPEN` - The invoice is open. Next valid states are PAYMENT_PENDING, PARTIALLY_PAID, PAID or ARCHIVED - `PAYMENT_PENDING` - The payment was initiated by Light and is waiting to be collected. Next valid state is PAID - `PARTIALLY_PAID` - The invoice is partially paid. Next valid state is PAID - `PAID` - The invoice is fully paid - `REVERSED` - The invoice was reversed by a credit note and reissued as a new invoice; it is locked and cannot be modified - `ARCHIVED` - The invoice is archived and cannot be modified ⚠️ This enum is not exhaustive; new values may be added in the future.
  - `openedAt` string, date-time, nullable: Timestamp when the invoice was opened
  - `poNumber` string, nullable: Purchase order number
  - `reference` string, nullable: Reference number for cross-referencing with procurement and invoicing workflows
  - `paymentReference` string, nullable: Payment reference generated by Light for the customer's bank payment
  - `description` string, nullable: Description of the invoice
  - `currency` string
  - `taxEngineName` 'AVATAX' | 'LIGHT' | 'SPHERE': Name of the tax engine to be used - `AVATAX` - Avalara AvaTax will be used for tax calculations - `LIGHT` - Light built-in tax engine will be used for tax calculations - `SPHERE` - Sphere tax engine will be used for tax calculations ⚠️ This enum is not exhaustive; new values may be added in the future.
  - `areLinesWithTax` boolean: Whether the invoice line amount is inclusive of tax or not. True means tax is already included in the line amount and will not be added on top, false means tax will be added on top of the line amount
  - `localCurrencyFxRate` number, nullable: Custom foreign exchange rate for the ledger's local currency. If not provided Light uses official ECB rates
  - `groupCurrencyFxRate` number, nullable: Custom foreign exchange rate for the ledger's group currency. If not provided Light uses official ECB rates
  - `lines` ExternalInvoiceReceivableLineV1Model[], nullable: List of invoice line items. This is only returned when fetching a single invoice by id
    - `id` string, uuid: Unique identifier for the object
    - `companyId` string, uuid: ID of the company
    - `invoiceReceivableId` string, uuid: ID of the invoice receivable this line belongs to
    - `productId` string, uuid: ID of the product
    - `quantity` number: Quantity of the product
    - `taxCodeId` string, uuid, nullable: ID of the tax code
    - `accountId` string, uuid, nullable: ID of the ledger account
    - `discount` ExternalAccountReceivableLineDiscountV1Model, nullable: Discount to apply to this line (can be percentage or amount-based)
      - `type` 'PERCENTAGE' | 'AMOUNT': ⚠️ This enum is not exhaustive; new values may be added in the future.
    - `discountAmount` integer, nullable: Discount amount in smallest denomination
    - `netAmount` integer, nullable: Net amount in smallest denomination after discount but before tax
    - `taxAmount` integer, nullable: Tax amount in smallest denomination
    - `avataxCode` string, nullable: Avalara tax code. Used when the invoice tax engine is `AVATAX`
    - `billingStart` string, date, nullable: Start of the billing period
    - `billingEnd` string, date, nullable: End of the billing period
    - `priceOverwrite` integer, nullable: Custom product price in smallest denomination. This overrides the default product's price
    - `productNameOverwrite` string, nullable: Custom product name. This overrides the default product's name
    - `createdAt` string, date-time: Timestamp when the line was created
    - `updatedAt` string, date-time: Timestamp when the line was last updated
    - `accrualTemplateId` string, uuid, nullable: ID of the accrual template
    - `accrualStartDate` string, date, nullable: Start date for accrual
    - `accrualEndDate` string, date, nullable: End date for accrual
    - `customProperties` ExternalCustomPropertyV1Model[], nullable: List of custom properties associated with the line
      - `groupId` string, uuid: ID of the custom property group
      - `groupInternalName` string: Internal name of the custom property group
      - `values` ExternalCustomPropertyValueV1Model[]: List of values. Note that this will be a single value unless the group input type supports multiple values
        - `id` string, uuid: Unique identifier for the object
        - `groupId` string, uuid: ID of the custom property group
        - `groupInternalName` string: Internal name of the custom property group
        - `companyId` string, uuid: ID of the company
        - `internalName` string: Internal name of the custom property value
        - `label` string: Label of the custom property value
        - `context` string, nullable: Context/description of the custom property value
        - `createdAt` string, date-time: Timestamp when the custom property value was created
        - `updatedAt` string, date-time: Timestamp when the custom property value was last updated
  - `customProperties` ExternalCustomPropertyV1Model[], nullable: List of custom properties associated with the invoice
    - `groupId` string, uuid: ID of the custom property group
    - `groupInternalName` string: Internal name of the custom property group
    - `values` ExternalCustomPropertyValueV1Model[]: List of values. Note that this will be a single value unless the group input type supports multiple values
      - `id` string, uuid: Unique identifier for the object
      - `groupId` string, uuid: ID of the custom property group
      - `groupInternalName` string: Internal name of the custom property group
      - `companyId` string, uuid: ID of the company
      - `internalName` string: Internal name of the custom property value
      - `label` string: Label of the custom property value
      - `context` string, nullable: Context/description of the custom property value
      - `createdAt` string, date-time: Timestamp when the custom property value was created
      - `updatedAt` string, date-time: Timestamp when the custom property value was last updated
  - `externalSource` ExternalApiExternalSourceV1Model, nullable: The external system where this product was synced from
    - `name` 'CHARGEBEE' | 'HUBSPOT' | 'SALESFORCE' | 'STRIPE': The name of the external source - `CHARGEBEE` - Data synced from Chargebee - `HUBSPOT` - Data synced from HubSpot - `SALESFORCE` - Data synced from Salesforce - `STRIPE` - Data synced from Stripe ⚠️ This enum is not exhaustive; new values may be added in the future.
    - `externalId` string: The ID of the object in the external source system
  - `createdAt` string, date-time: Timestamp when the invoice was created
  - `updatedAt` string, date-time: Timestamp when the invoice was last updated
  - `updatedBy` string, uuid, nullable: ID of the user who last updated the invoice
  - `failureContext` ExternalUiClientExceptionV1Model, nullable: Failure context when vendor onboarding fails.
    - `name` string: The error name
    - `type` 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'CONFLICT' | 'UNPROCESSABLE_CONTENT': The error type ⚠️ This enum is not exhaustive; new values may be added in the future.
    - `errors` ExternalUiClientExceptionErrorV1Model[]: List of errors providing details about what went wrong
      - `type` string: A string code identifying the error type
      - `message` string: A human-readable message providing more details about the error
      - `path` string[], nullable: Optional path of the error when the error is for a specific field. Used mostly on BAD_REQUEST errors, that path will match the field name on the request object
      - `context` object, nullable: Optional context providing additional information about the error. This can include any relevant data that might help in understanding or resolving the error

---

[API](https://skmtc.dev/light/apis/light-api.md) - [All operations](https://skmtc.dev/light/apis/light-api/llms.txt) - [OpenAPI document](https://skmtc.dev/light/apis/light-api/revisions/84f51306f648?raw)