Create bills in bulk
https://api.light.inc/v1/invoice-payables/batch-create
Creates data-only bills as drafts. Set post to true to post each bill without approval, skipping the company's bill approval workflow. This requires the single-bill posting permission. Null entries in a bill's lineItems or customProperties lists reject the request. An already-posted bill completes without another posting. A posting failure retains the bill ID. AI-mode rows fail individually. Submit up to 1,000 records and 100,000 lineItems per call. A company can have up to 20,000 records waiting. On a 429 response, retry after the number of seconds in the Retry-After header.
Permissions checked: bills:create (AP_CLERK, AP_PREPARATION, COMPANY_ADMIN, CONTROLLER) and bills:post (COMPANY_ADMIN). What a call needs depends on the caller, the record and the request.
Authorization
Send one of these on every request. See Authentication for how to get credentials.
- API key
Basic authentication header of the form Basic <api_key>, where <api_key> is your api key.
- Bearer token
Request body
application/json;charset=UTF-8 · required
-
recordsarray of objectrequiredEach bill requires a nonblank idempotencyKey unique within the call. Blank, whitespace-only and NUL-containing keys are rejected.
-
idempotencyKeystringrequiredA key you choose for this record, unique within the call. On retry, send the same record and key. Light returns the original record ID if it processes the retry while the successful create is still cached (24 hours after creation).
-
recordobjectrequired-
vendorIdstring · uuidID of the vendor.
-
amountinteger · int64Invoice total amount in cents.
-
currencystringInvoice currency.
Note
ISO 4217 code of the invoice currency.
-
processingModestringHow the invoice should be processed (skip AI Parse or AI Parse + merge).
⚠️ This enum is not exhaustive; new values may be added in the future.
Note
With
AI_PARSE_AND_MERGEonlyvendorId,amountandcurrencyare read; every other field in this body is dropped, and the bill waits inCREATEDfor a document upload. UseDATA_ONLYto store what you send.One of
DATA_ONLYAI_PARSE_AND_MERGE -
typestringType of bill to create.
SELF_BILLEDcreates a self-billed invoice that you issue on the vendor's behalf: it starts as a draft and takes the company entity's next self-billed number when it is submitted or posted, unlessinvoiceNumberis set. Rejected whenprocessingModeisAI_PARSE_AND_MERGE.⚠️ This enum is not exhaustive; new values may be added in the future.
One of
VENDOR_INVOICESELF_BILLED -
documentTemplateIdstring · uuidID of the self-billed document template used to render the bill. Must be an active self-billed template assigned to
companyEntityId. When omitted on a self-billed bill, the newest active self-billed template of the company entity is used. Rejected whenprocessingModeisAI_PARSE_AND_MERGE. -
companyEntityIdstring · uuidID of the company entity.
-
invoiceNumberstringInvoice number.
-
descriptionstringInvoice description.
-
issuedDatestring · dateIssue date of the original vendor invoice.
-
postingDatestring · dateDate the invoice payable is posted to the ledger, which sets its accounting period independently of the issued date. Defaults to the issued date when omitted on creation.
-
dueDatestring · datePayment due date of the invoice payable.
-
paymentAtstring · date-timeDate/time when payment is scheduled or was executed for this invoice payable.
-
senderBankAccountIdstring · uuidID of the sender bank account from which this invoice payable will be paid.
-
lineItemsIncludeTaxbooleanWhether invoice line item amounts are entered as tax-inclusive. When true, line item
amountis expected to be the gross amount including tax; when false, line itemnetAmountis expected to be the base amount excluding tax. -
lineItemsarray of objectList of line items to create with the invoice. This allows creating the invoice header and its line items in a single request.
-
amountinteger · int64Gross line amount in cents, including tax. Set this when the parent invoice header field
lineItemsIncludeTaxis true. WhenlineItemsIncludeTaxis false, prefer usingnetAmountinstead and avoid sending both. -
netAmountinteger · int64Net line amount in cents, excluding tax. Set this when the parent invoice header field
lineItemsIncludeTaxis false. WhenlineItemsIncludeTaxis true, prefer usingamountinstead and avoid sending both. -
taxAmountinteger · int64Tax amount for this line in cents. If omitted, tax may be derived from the configured tax code and base amount.
-
descriptionstringDescription for this invoice payable line item.
-
taxCodeIdstring · uuidID of the tax code to apply to this invoice payable line item.
-
accountIdstring · uuidID of the ledger account to book this invoice payable line item against.
-
amortizationStartDatestring · dateStart date for amortization of this invoice payable line item.
-
amortizationEndDatestring · dateEnd date for amortization of this invoice payable line item.
-
amortizationTemplateIdstring · uuidID of the amortization template to apply to this line item using Light Ledger.
-
customPropertiesarray of objectCustom properties to set on this invoice payable line item.
-
groupIdstring · uuidID of the custom property group.
-
valueIdsarray of string · uuidIDs of the selected custom property values. It behaves as a PUT operation, so if empty the existing ones will be effectively deleted.
Note
Catalog value ids for this group. Required; send
[](with an emptyinlineValues) to clear the group.SINGLE_SELECTandMULTI_SELECTgroups accept nothing else. See Custom properties on writes. -
inlineValuesarray of stringInline 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.
Note
Literal values for
TEXT,NUMERIC,BOOLEANandDATEgroups, as strings (yyyy-MM-ddfor dates). Rejected on select groups withCUSTOM_PROPERTY_VALUE_TYPE_MISMATCH. See Custom properties on writes. -
attachmentIdsarray of string · uuidIDs of attachments to assign to an ATTACHMENT property on an existing vendor. Send valueIds as an empty list. Only one active attachment belonging to the vendor can be assigned per group. Clear the current file before assigning another. Create the vendor first, request POST /v1/attachments/upload-url with its resourceId, upload the file to the returned URL, then POST /v1/attachments with documentKey set to the returned key. Use the created attachment's id here in PUT or PATCH /v1/vendors/{vendorId}. A PATCH that sends only customProperties and changes only their files works in every vendor status. customProperties replaces the whole set, so send the vendor's other properties as they are, by valueIds. A PUT, or a PATCH that changes anything else, returns 400 while the vendor is IN_REVIEW, ONBOARDING or INACTIVE. An empty list clears the assignment without archiving the file.
-
-
-
customPropertiesarray of objectList of custom properties to set on the invoice.
-
groupIdstring · uuidID of the custom property group.
-
valueIdsarray of string · uuidIDs of the selected custom property values. It behaves as a PUT operation, so if empty the existing ones will be effectively deleted.
Note
Catalog value ids for this group. Required; send
[](with an emptyinlineValues) to clear the group.SINGLE_SELECTandMULTI_SELECTgroups accept nothing else. See Custom properties on writes. -
inlineValuesarray of stringInline 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.
Note
Literal values for
TEXT,NUMERIC,BOOLEANandDATEgroups, as strings (yyyy-MM-ddfor dates). Rejected on select groups withCUSTOM_PROPERTY_VALUE_TYPE_MISMATCH. See Custom properties on writes. -
attachmentIdsarray of string · uuidIDs of attachments to assign to an ATTACHMENT property on an existing vendor. Send valueIds as an empty list. Only one active attachment belonging to the vendor can be assigned per group. Clear the current file before assigning another. Create the vendor first, request POST /v1/attachments/upload-url with its resourceId, upload the file to the returned URL, then POST /v1/attachments with documentKey set to the returned key. Use the created attachment's id here in PUT or PATCH /v1/vendors/{vendorId}. A PATCH that sends only customProperties and changes only their files works in every vendor status. customProperties replaces the whole set, so send the vendor's other properties as they are, by valueIds. A PUT, or a PATCH that changes anything else, returns 400 while the vendor is IN_REVIEW, ONBOARDING or INACTIVE. An empty list clears the assignment without archiving the file.
-
-
localCurrencyFxRateOverridenumberCustom FX rate for the ledger's local currency. If not provided, Light uses official ECB rates.
-
groupCurrencyFxRateOverridenumberCustom FX rate for the ledger's group currency. If not provided, Light uses official ECB rates.
-
-
-
postbooleanPost each created bill without approval, skipping the company's bill approval workflow. Defaults to false. A failed post retains the bill ID.
Response
The bills were accepted for processing
-
idstring · uuidUnique identifier of the batch operation
-
companyIdstring · uuidID of the company the batch operation belongs to
-
namestringWhat the batch operation does
⚠️ This enum is not exhaustive; new values may be added in the future.
One of
BATCH_CREATE_CREDIT_NOTESBATCH_CREATE_CUSTOMERSBATCH_CREATE_CUSTOMER_CREDITSBATCH_CREATE_INVOICE_PAYABLESBATCH_CREATE_INVOICE_RECEIVABLESBATCH_UPDATE_CARD_TRANSACTIONS -
statusstringIN_PROGRESSuntil no record is pending. ThenCOMPLETED, orFAILEDwhen at least one record failedCOMPLETED- Every record was processedFAILED- No record is pending and at least one failedIN_PROGRESS- At least one record is pending
⚠️ This enum is not exhaustive; new values may be added in the future.
One of
COMPLETEDFAILEDIN_PROGRESS -
initiatedBystring · uuidID of the user or API key that started the batch operation
-
createdAtstring · date-timeWhen the batch operation was created
-
pendingItemCountinteger · int64Number of records waiting to be processed
-
completedItemCountinteger · int64Number of records that were processed
-
failedItemCountinteger · int64Number of records that failed