Create vendor credit notes in bulk
https://api.light.inc/v1/credit-notes/batch-create
Creates draft vendor credit notes asynchronously, in no particular order. Supply an idempotency key for each record. A worker processing the same record for the same initiator and key within 24 hours of the original creation returns its ID if the credit note is still accessible. Poll the batch operation until it leaves IN_PROGRESS, then read its items for each record's ID or error. A failed record does not stop the others. A call accepts up to 1,000 records and 100,000 lines in total. Exceeding the company limit of 20,000 pending records returns 429 with a Retry-After header.
Permission: credit-notes:create (AP_CLERK, AP_PREPARATION, COMPANY_ADMIN, CONTROLLER)
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 objectrequiredThe vendor credit notes to create
-
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-
companyEntityIdstring · uuidID of the entity
-
currencystringrequiredCurrency of the credit note
-
documentDatestring · daterequiredDate when the credit note was issued
-
businessPartnerIdstring · uuidID of the vendor (required if the credit note will be linked to an invoice payable)
-
descriptionstringDescription of the credit note
-
amountinteger · int64Total credit note amount in cents
-
areLinesWithTaxbooleanWhether line amounts include tax. true = tax included (gross), false = tax added on top (net)
-
documentNumberstringVendor's credit note number. Reusing a number in the same company can cause a conflict, even across vendors. A single create uses this number for idempotency when no explicit key is supplied.
-
customPropertiesarray of objectList of custom properties
-
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.
-
-
linesarray of objectList of credit note line items
-
netTransactionAmountobject-
amountinteger · int64Note
Unsigned integer in minor units. The direction is in
dcSign; a negative value is rejected. -
dcSignstring⚠️ This enum is not exhaustive; new values may be added in the future.
One of
DC
-
-
grossTransactionAmountobject-
amountinteger · int64Note
Unsigned integer in minor units. The direction is in
dcSign; a negative value is rejected. -
dcSignstring⚠️ This enum is not exhaustive; new values may be added in the future.
One of
DC
-
-
taxTransactionAmountobject-
amountinteger · int64Note
Unsigned integer in minor units. The direction is in
dcSign; a negative value is rejected. -
dcSignstring⚠️ This enum is not exhaustive; new values may be added in the future.
One of
DC
-
-
descriptionstringLine description
-
ledgerTaxIdstring · uuidID of the tax code
-
ledgerAccountIdstring · uuidID of the ledger account
-
customPropertiesarray of objectList of custom properties for this 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.
-
-
accrualTemplateIdstring · uuidID of the accrual template
-
accrualStartDatestring · dateStart date for accrual
-
accrualEndDatestring · dateEnd date for accrual
-
-
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.
-
-
Response
The credit notes were accepted for creation.
-
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