Create invoices in bulk
https://api.light.inc/v1/invoice-receivables/batch-create
Creates many sales invoices in one call, and opens them when open is given. The call answers at once with a batch operation; the invoices are created afterwards, in no particular order. Read the batch operation until its status is no longer IN_PROGRESS, then read its items for the result of each record. Each record is created as Create invoice creates it, and a record that fails does not stop the others. A call can hold up to 1,000 records with up to 100,000 lines between them. A company can have up to 20,000 records waiting. Past that the call is refused with 429: send it again after the number of seconds in the Retry-After header.
Permissions checked: invoices/emails:create (AR_CLERK, COMPANY_ADMIN, CONTROLLER), invoices:create (AR_CLERK, COMPANY_ADMIN, CONTROLLER) and invoices:post (AR_CLERK, COMPANY_ADMIN, CONTROLLER). 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
-
recordsarray of objectThe invoices to create
-
idempotencyKeystringA key you choose for this record, unique within the call. A record sent again with the same key within 24 hours is not created twice: its item completes with the ID of the record created the first time
-
recordobject-
companyEntityIdstring · uuidID of the company entity
-
invoiceNumberstringUnique invoice number. If not provided, one will be generated automatically when the invoice is opened.
-
descriptionstringInvoice description
-
currencystringInvoice currency
Note
ISO 4217 code. Defaults to the customer's currency, else the entity's.
-
paymentTypestringPayment type for the invoice
AIRWALLEX- Payment via Airwallex. A payment link will be displayed on the invoiceBANK_TRANSFER- Payment via bank transfer. Bank information will be displayed on the invoiceDIRECT_DEBIT- Payment via direct debit. A notice that the amount will be collected automatically will be displayed on the invoiceSTRIPE- 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.
One of
AIRWALLEXBANK_TRANSFERDIRECT_DEBITSTRIPE -
payeeBankAccountIdstring · uuidID of the bank account where money should be sent to
-
invoiceDatestring · dateDate the invoice was issued
-
postingDatestring · dateDate the invoice is posted to the ledger (drives GL, VAT and revenue recognition). Defaults to the invoice date when omitted.
-
dueDatestring · dateDate the invoice payment is due
-
customerIdstring · uuidID of the customer
-
invoiceTemplateIdstring · uuidID of the invoice template
-
netTermsinteger · int32Number of days from the invoice date to when the invoice is due. Setting this will automatically calculate the due date
-
poNumberstringPurchase order number
-
referencestringReference number for cross-referencing with procurement and invoicing workflows
-
invoiceTemplateAdditionalTextstringText that will be added to the additional text section of the invoice template
-
areLinesWithTaxbooleanWhether 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
-
localCurrencyFxRatenumberCustom foreign exchange rate for the ledger's local currency. If not provided, Light uses official ECB rates
-
groupCurrencyFxRatenumberCustom foreign exchange rate for the ledger's group currency. If not provided, Light uses official ECB rates
-
linesarray of objectList of invoice line items to create
-
productIdstring · uuidID of the product
-
quantitynumberQuantity of the product
-
taxCodeIdstring · uuidID of the tax code to apply to this line
-
accountIdstring · uuidID of the ledger account for this line
-
discountobjectDiscount to apply to this line (can be percentage or amount-based)
Note
Optional discount on the line, by percentage or by amount.
-
typestring⚠️ This enum is not exhaustive; new values may be added in the future.
One of
PERCENTAGEAMOUNT
-
-
priceOverwriteinteger · int64Price overwrite in smallest denomination. If not provided, the product's default price will be used
-
productNameOverwritestringProduct name overwrite. If not provided, the product's default name will be used
-
taxAmountOverwriteinteger · int64Tax 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.
-
avataxCodestringAvalara tax code. Used when the invoice tax engine is AVATAX
-
billingStartstring · dateStart of the billing period for this line
-
billingEndstring · dateEnd of the billing period for this line
-
accrualTemplateIdstring · uuidID of the accrual/amortization template to apply to this line
-
accrualStartDatestring · dateStart date for accrual/amortization
-
accrualEndDatestring · dateEnd date for accrual/amortization
-
customPropertiesarray of objectList of custom properties to set on the invoice or line
-
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 or line
-
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.
-
-
-
-
openobjectOpens each invoice after it is created. Leave it out to keep the invoices as drafts
-
shouldSendEmailbooleanWhether to email each invoice to its customer when opening. The email goes to the customer's invoice recipients. Defaults to false
-
shouldSubmitEInvoicebooleanWhether to submit the invoice to the e-invoicing system (if configured). Defaults to false
-
Response
The invoices were accepted. Every record is `PENDING` until it is created, and opened when `open` was given.
-
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_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