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

Create customer credits in bulk

POST
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

  • records array of objectrequired

    The customer credits 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

      • documentNumber string

        Unique customer credit number. If not provided, one will be generated automatically when the invoice is opened.

      • description string

        Description of the customer credit

      • currency string

        Currency of the customer credit

      • localCurrencyFxRate number

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

      • groupCurrencyFxRate number

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

      • documentDate string · date

        Date when the customer credit was issued

      • postingDate string · date

        Date when the customer credit is posted to the ledger. Defaults to the document date, or today if both dates are omitted

      • documentTemplateId string · uuid

        ID of the document template that the customer credit will use

      • areLinesWithTax boolean

        Whether 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

      • customerId string · uuid

        ID of the customer

      • amount integer · int64

        Total customer credit amount in cents

      • lines array of object

        List of customer credit line items

        • productId string · uuid

          ID of the product

        • quantity number

          Quantity of the product

        • 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

          Description of the customer credit line item

        • ledgerTaxId string · uuid

          ID of the tax code

        • ledgerAccountId string · uuid

          ID of the ledger account

        • avataxCode string

          Avalara tax code. Used when the customer credit tax engine is AVATAX

        • customProperties array of object

          List of custom properties associated with the 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

      • customProperties array of object

        List of custom properties associated with the customer credit

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

Response

The customer credits were accepted. Each item starts as PENDING.

  • 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