New Light partners with Greenstep to bring agentic finance to the NordicsLight partners with Greenstep Read the announcement

Create invoices in bulk

POST
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

  • records array of object

    The invoices to create

    • idempotencyKey string

      A 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

    • record object

      • companyEntityId string · uuid

        ID of the company entity

      • invoiceNumber string

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

      • description string

        Invoice description

      • currency string

        Invoice currency

        Note

        ISO 4217 code. Defaults to the customer's currency, else the entity's.

      • paymentType string

        Payment type for the invoice

        • AIRWALLEX - Payment via Airwallex. A payment link will be displayed on the invoice
        • BANK_TRANSFER - Payment via bank transfer. Bank information will be displayed on the invoice
        • DIRECT_DEBIT - Payment via direct debit. A notice that the amount will be collected automatically will be displayed on the invoice
        • STRIPE - 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 AIRWALLEX BANK_TRANSFER DIRECT_DEBIT STRIPE

      • payeeBankAccountId string · uuid

        ID of the bank account where money should be sent to

      • invoiceDate string · date

        Date the invoice was issued

      • postingDate string · date

        Date the invoice is posted to the ledger (drives GL, VAT and revenue recognition). Defaults to the invoice date when omitted.

      • dueDate string · date

        Date the invoice payment is due

      • customerId string · uuid

        ID of the customer

      • invoiceTemplateId string · uuid

        ID of the invoice template

      • netTerms integer · int32

        Number of days from the invoice date to when the invoice is due. Setting this will automatically calculate the due date

      • poNumber string

        Purchase order number

      • reference string

        Reference number for cross-referencing with procurement and invoicing workflows

      • invoiceTemplateAdditionalText string

        Text that will be added to the additional text section of the invoice template

      • areLinesWithTax boolean

        Whether 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

      • 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

      • lines array of object

        List of invoice line items to create

        • productId string · uuid

          ID of the product

        • quantity number

          Quantity of the product

        • taxCodeId string · uuid

          ID of the tax code to apply to this line

        • accountId string · uuid

          ID of the ledger account for this line

        • discount object

          Discount to apply to this line (can be percentage or amount-based)

          Note

          Optional discount on the line, by percentage or by amount.

          • type string

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

            One of PERCENTAGE AMOUNT

        • priceOverwrite integer · int64

          Price overwrite in smallest denomination. If not provided, the product's default price will be used

        • productNameOverwrite string

          Product name overwrite. If not provided, the product's default name will be used

        • taxAmountOverwrite integer · int64

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

        • avataxCode string

          Avalara tax code. Used when the invoice tax engine is AVATAX

        • billingStart string · date

          Start of the billing period for this line

        • billingEnd string · date

          End of the billing period for this line

        • accrualTemplateId string · uuid

          ID of the accrual/amortization template to apply to this line

        • accrualStartDate string · date

          Start date for accrual/amortization

        • accrualEndDate string · date

          End date for accrual/amortization

        • customProperties array of object

          List of custom properties to set on the invoice or 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.

      • customProperties array of object

        List of custom properties to set on the invoice or 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.

  • open object

    Opens each invoice after it is created. Leave it out to keep the invoices as drafts

    • shouldSendEmail boolean

      Whether to email each invoice to its customer when opening. The email goes to the customer's invoice recipients. Defaults to false

    • shouldSubmitEInvoice boolean

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

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