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

Create line

POST
https://api.light.inc/v1/invoice-receivables/{invoiceReceivableId}/lines

Creates a new invoice line item

Permission: invoices:update (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

Path parameters

  • invoiceReceivableId string · uuidrequired

Request body

application/json;charset=UTF-8

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

Response

  • id string · uuid

    Unique identifier for the object

  • companyId string · uuid

    ID of the company

  • invoiceReceivableId string · uuid

    ID of the invoice receivable this line belongs to

  • productId string · uuid

    ID of the product

  • quantity number

    Quantity of the product

  • taxCodeId string · uuid

    ID of the tax code

  • taxRate number

    Current nominal VAT rate of the assigned Light tax code as a fraction: 0.25 is 25%. Tax-code edits change this value, including on issued documents, without changing stored line amounts. This is not tax divided by net: posting rules, rounding and overrides can change that ratio. Excludes withholding. Null for an exempt tax code or when no Light tax code is assigned

  • taxCode string

    Current short code of the assigned Light tax code. Null when no Light tax code is assigned

  • taxName string

    Current display name of the assigned Light tax code. Null when the name or tax code is absent

  • withholdings array of object

    Withholdings recorded on this line. Later tax-code configuration edits do not change these snapshots. Empty when the line has none. These do not reduce the VAT or gross amounts

    • rate number

      Recorded withholding rate as a fraction: 0.20 is 20%

    • taxableBasePct number

      Percentage of the line net amount subject to withholding: 100 means the full net amount

    • amount integer · int64

      Recorded withholding amount in the document currency's smallest denomination, using the same sign as the line's net amount. Negative for a reversing line

  • accountId string · uuid

    ID of the ledger account

  • discount object

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

    Note

    Discount applied to 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

  • discountAmount integer · int64

    Discount amount in smallest denomination

  • netAmount integer · int64

    Net amount in smallest denomination after discount but before tax

    Note

    Signed: credit-side lines are positive, debit-side lines (a negative priceOverwrite) are negative. discountAmount is unsigned.

  • taxAmount integer · int64

    Tax amount in smallest denomination

    Note

    Signed the same way as netAmount: negative on a debit-side line.

  • avataxCode string

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

  • billingStart string · date

    Start of the billing period

  • billingEnd string · date

    End of the billing period

  • priceOverwrite integer · int64

    Custom product price in smallest denomination. This overrides the default product's price

  • productNameOverwrite string

    Custom product name. This overrides the default product's name

  • createdAt string · date-time

    Timestamp when the line was created

  • updatedAt string · date-time

    Timestamp when the line was last updated

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

    • groupId string · uuid

      ID of the custom property group

    • groupInternalName string

      Internal name of the custom property group

    • values array of object

      List of values. Note that this will be a single value unless the group input type supports multiple values

      • id string · uuid

        Unique identifier for the object

      • groupId string · uuid

        ID of the custom property group

      • groupInternalName string

        Internal name of the custom property group

      • companyId string · uuid

        ID of the company

      • internalName string

        Internal name of the custom property value

      • label string

        Label of the custom property value

      • context string

        Context/description of the custom property value

      • createdAt string · date-time

        Timestamp when the custom property value was created

      • updatedAt string · date-time

        Timestamp when the custom property value was last updated

      • attachment object

        File assigned to an ATTACHMENT property. Null for other property types.

        • id string · uuid

          Attachment ID. Use GET /v1/attachments/{attachmentId}/document to download the file.

        • fileName string

        • contentType string