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

Create bills in bulk

POST
https://api.light.inc/v1/invoice-payables/batch-create

Creates data-only bills as drafts. Set post to true to post each bill without approval, skipping the company's bill approval workflow. This requires the single-bill posting permission. Null entries in a bill's lineItems or customProperties lists reject the request. An already-posted bill completes without another posting. A posting failure retains the bill ID. AI-mode rows fail individually. Submit up to 1,000 records and 100,000 lineItems per call. A company can have up to 20,000 records waiting. On a 429 response, retry after the number of seconds in the Retry-After header.

Permissions checked: bills:create (AP_CLERK, AP_PREPARATION, COMPANY_ADMIN, CONTROLLER) and bills:post (COMPANY_ADMIN). 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 · required

  • records array of objectrequired

    Each bill requires a nonblank idempotencyKey unique within the call. Blank, whitespace-only and NUL-containing keys are rejected.

    • 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

      • vendorId string · uuid

        ID of the vendor.

      • amount integer · int64

        Invoice total amount in cents.

      • currency string

        Invoice currency.

        Note

        ISO 4217 code of the invoice currency.

      • processingMode string

        How the invoice should be processed (skip AI Parse or AI Parse + merge).

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

        Note

        With AI_PARSE_AND_MERGE only vendorId, amount and currency are read; every other field in this body is dropped, and the bill waits in CREATED for a document upload. Use DATA_ONLY to store what you send.

        One of DATA_ONLY AI_PARSE_AND_MERGE

      • type string

        Type of bill to create. SELF_BILLED creates a self-billed invoice that you issue on the vendor's behalf: it starts as a draft and takes the company entity's next self-billed number when it is submitted or posted, unless invoiceNumber is set. Rejected when processingMode is AI_PARSE_AND_MERGE.

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

        One of VENDOR_INVOICE SELF_BILLED

      • documentTemplateId string · uuid

        ID of the self-billed document template used to render the bill. Must be an active self-billed template assigned to companyEntityId. When omitted on a self-billed bill, the newest active self-billed template of the company entity is used. Rejected when processingMode is AI_PARSE_AND_MERGE.

      • companyEntityId string · uuid

        ID of the company entity.

      • invoiceNumber string

        Invoice number.

      • description string

        Invoice description.

      • issuedDate string · date

        Issue date of the original vendor invoice.

      • postingDate string · date

        Date the invoice payable is posted to the ledger, which sets its accounting period independently of the issued date. Defaults to the issued date when omitted on creation.

      • dueDate string · date

        Payment due date of the invoice payable.

      • paymentAt string · date-time

        Date/time when payment is scheduled or was executed for this invoice payable.

      • senderBankAccountId string · uuid

        ID of the sender bank account from which this invoice payable will be paid.

      • lineItemsIncludeTax boolean

        Whether invoice line item amounts are entered as tax-inclusive. When true, line item amount is expected to be the gross amount including tax; when false, line item netAmount is expected to be the base amount excluding tax.

      • lineItems array of object

        List of line items to create with the invoice. This allows creating the invoice header and its line items in a single request.

        • amount integer · int64

          Gross line amount in cents, including tax. Set this when the parent invoice header field lineItemsIncludeTax is true. When lineItemsIncludeTax is false, prefer using netAmount instead and avoid sending both.

        • netAmount integer · int64

          Net line amount in cents, excluding tax. Set this when the parent invoice header field lineItemsIncludeTax is false. When lineItemsIncludeTax is true, prefer using amount instead and avoid sending both.

        • taxAmount integer · int64

          Tax amount for this line in cents. If omitted, tax may be derived from the configured tax code and base amount.

        • description string

          Description for this invoice payable line item.

        • taxCodeId string · uuid

          ID of the tax code to apply to this invoice payable line item.

        • accountId string · uuid

          ID of the ledger account to book this invoice payable line item against.

        • amortizationStartDate string · date

          Start date for amortization of this invoice payable line item.

        • amortizationEndDate string · date

          End date for amortization of this invoice payable line item.

        • amortizationTemplateId string · uuid

          ID of the amortization template to apply to this line item using Light Ledger.

        • customProperties array of object

          Custom properties to set on this invoice payable line item.

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

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

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

  • post boolean

    Post each created bill without approval, skipping the company's bill approval workflow. Defaults to false. A failed post retains the bill ID.

Response

The bills were accepted for processing

  • 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