New Light partners with Amesto GlobalLight partners with Amesto Global Read the announcement

Create vendor credit notes in bulk

POST
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

  • records array of objectrequired

    The vendor credit notes to create

    • idempotencyKey stringrequired

      A 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).

    • record objectrequired

      • companyEntityId string · uuid

        ID of the entity

      • currency stringrequired

        Currency of the credit note

      • documentDate string · daterequired

        Date when the credit note was issued

      • businessPartnerId string · uuid

        ID of the vendor (required if the credit note will be linked to an invoice payable)

      • description string

        Description of the credit note

      • amount integer · int64

        Total credit note amount in cents

      • areLinesWithTax boolean

        Whether line amounts include tax. true = tax included (gross), false = tax added on top (net)

      • documentNumber string

        Vendor'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.

      • customProperties array of object

        List of custom properties

        • groupId string · uuid

          ID of the custom property group.

        • valueIds array of string · uuid

          IDs 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 empty inlineValues) to clear the group. SINGLE_SELECT and MULTI_SELECT groups accept nothing else. See Custom properties on writes.

        • inlineValues array of string

          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.

          Note

          Literal values for TEXT, NUMERIC, BOOLEAN and DATE groups, as strings (yyyy-MM-dd for dates). Rejected on select groups with CUSTOM_PROPERTY_VALUE_TYPE_MISMATCH. See Custom properties on writes.

        • attachmentIds array of string · uuid

          IDs 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.

      • lines array of object

        List of credit note line items

        • netTransactionAmount object

          • amount integer · int64

            Note

            Unsigned integer in minor units. The direction is in dcSign; a negative value is rejected.

          • dcSign string

            ⚠️ This enum is not exhaustive; new values may be added in the future.

            One of D C

        • grossTransactionAmount object

          • amount integer · int64

            Note

            Unsigned integer in minor units. The direction is in dcSign; a negative value is rejected.

          • dcSign string

            ⚠️ This enum is not exhaustive; new values may be added in the future.

            One of D C

        • taxTransactionAmount object

          • amount integer · int64

            Note

            Unsigned integer in minor units. The direction is in dcSign; a negative value is rejected.

          • dcSign string

            ⚠️ This enum is not exhaustive; new values may be added in the future.

            One of D C

        • description string

          Line description

        • ledgerTaxId string · uuid

          ID of the tax code

        • ledgerAccountId string · uuid

          ID of the ledger account

        • customProperties array of object

          List of custom properties for this line

          • groupId string · uuid

            ID of the custom property group.

          • valueIds array of string · uuid

            IDs 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 empty inlineValues) to clear the group. SINGLE_SELECT and MULTI_SELECT groups accept nothing else. See Custom properties on writes.

          • inlineValues array of string

            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.

            Note

            Literal values for TEXT, NUMERIC, BOOLEAN and DATE groups, as strings (yyyy-MM-dd for dates). Rejected on select groups with CUSTOM_PROPERTY_VALUE_TYPE_MISMATCH. See Custom properties on writes.

          • attachmentIds array of string · uuid

            IDs 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.

        • accrualTemplateId string · uuid

          ID of the accrual template

        • accrualStartDate string · date

          Start date for accrual

        • accrualEndDate string · date

          End date for accrual

      • localCurrencyFxRateOverride number

        Custom FX rate for the ledger's local currency. If not provided, Light uses official ECB rates.

      • groupCurrencyFxRateOverride number

        Custom FX rate for the ledger's group currency. If not provided, Light uses official ECB rates.

Response

The credit notes were accepted for creation.

  • id string · uuid

    Unique identifier of the batch operation

  • companyId string · uuid

    ID of the company the batch operation belongs to

  • name string

    What the batch operation does

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of BATCH_CREATE_CREDIT_NOTES BATCH_CREATE_CUSTOMERS BATCH_CREATE_CUSTOMER_CREDITS BATCH_CREATE_INVOICE_PAYABLES BATCH_CREATE_INVOICE_RECEIVABLES BATCH_UPDATE_CARD_TRANSACTIONS

  • status string

    IN_PROGRESS until no record is pending. Then COMPLETED, or FAILED when at least one record failed

    • COMPLETED - Every record was processed
    • FAILED - No record is pending and at least one failed
    • IN_PROGRESS - At least one record is pending

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of COMPLETED FAILED IN_PROGRESS

  • initiatedBy string · uuid

    ID of the user or API key that started the batch operation

  • createdAt string · date-time

    When the batch operation was created

  • pendingItemCount integer · int64

    Number of records waiting to be processed

  • completedItemCount integer · int64

    Number of records that were processed

  • failedItemCount integer · int64

    Number of records that failed