Create customer credits in bulk
https://api.light.inc/v1/customer-credits/batch-create
Accepts up to 1,000 customer credits with up to 100,000 lines in total. Each record uses the same fields as a single customer credit. Credits are created independently, in no particular order. Poll the batch operation, then read its items for each credit ID or error. Send the same record with its original idempotency key to replay a create. A company can have up to 20,000 pending records. On HTTP 429, retry after the number of seconds in the Retry-After header.
Permission: customer-credits:create (AR_CLERK, 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 customer credits 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
-
documentNumberstringUnique customer credit number. If not provided, one will be generated automatically when the invoice is opened.
-
descriptionstringDescription of the customer credit
-
currencystringCurrency of the customer credit
-
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
-
documentDatestring · dateDate when the customer credit was issued
-
postingDatestring · dateDate when the customer credit is posted to the ledger. Defaults to the document date, or today if both dates are omitted
-
documentTemplateIdstring · uuidID of the document template that the customer credit will use
-
areLinesWithTaxbooleanWhether the customer credit 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
-
customerIdstring · uuidID of the customer
-
amountinteger · int64Total customer credit amount in cents
-
linesarray of objectList of customer credit line items
-
productIdstring · uuidID of the product
-
quantitynumberQuantity of the product
-
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
-
-
descriptionstringDescription of the customer credit line item
-
ledgerTaxIdstring · uuidID of the tax code
-
ledgerAccountIdstring · uuidID of the ledger account
-
avataxCodestringAvalara tax code. Used when the customer credit tax engine is AVATAX
-
customPropertiesarray of objectList of custom properties associated with the 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
-
-
customPropertiesarray of objectList of custom properties associated with the customer credit
-
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.
-
-
-
Response
The customer credits were accepted. Each item starts as PENDING.
-
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