Light APIv1.0.0

API / Reference / Contracts

Create contract line

POST https://api.light.inc/v1/contracts/{contractId}/lines

Creates a new contract line item

Only while the contract is DRAFT (CONTRACT_CANNOT_BE_MODIFIED). A line discount carries its own startDate and endDate window in addition to type and value.

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

  • contractId string · uuidrequired

Headers

  • X-Idempotency-Key string

Request body

application/json;charset=UTF-8

  • productId string · uuid

    ID of the product

  • billingStart string · date

    Date when billing starts for this line

  • billingEnd string · date

    Date when billing ends for this line

  • billingRecurrence string

    Billing frequency for this line

    • ONE_TIME - The product is billed once
    • MONTHLY - The product is billed every month
    • QUARTERLY - The product is billed every three months
    • HALF_YEARLY - The product is billed every six months
    • YEARLY - The product is billed every year

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

    One of ONE_TIME MONTHLY QUARTERLY HALF_YEARLY YEARLY

  • accountId string · uuid

    ID of the ledger account for this line

  • taxCodeId string · uuid

    ID of the tax code to apply to this line

  • avataxCode string

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

  • discount object

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

    • startDate string · date

    • endDate string · date

    • type string

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

      One of PERCENTAGE AMOUNT

  • quantity number

    Quantity of the product

  • priceOverwrite integer · int64

    Custom price override in cents

    The line total before discount, in the smallest denomination — not a unit price. It replaces quantity × the product's price, and the unit price Light displays is this figure divided by quantity: 10 units at $0.20 each is 200 with quantity: 10, while 20 prices the whole line at $0.20. Any line discount then applies on top, so 20 with a 50% discount leaves the line at $0.10. Required when the product has no price in the contract's currency.

  • productNameOverwrite string

    Custom product name override

  • customProperties array of object

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

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

      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.

  • amortizationTemplateId string · uuid

    ID of the amortization template

  • amortizationStartDate string · date

    Start date for amortization

  • amortizationEndDate string · date

    End date for amortization

Response

  • id string · uuid

    Unique identifier for the object

  • companyId string · uuid

    ID of the company

  • contractId string · uuid

    ID of the contract this line belongs to

  • productId string · uuid

    ID of the product

  • billingStart string · date

    Date when billing starts for this line

  • billingEnd string · date

    Date when billing ends for this line

  • billingRecurrence string

    Billing frequency for this line

    • ONE_TIME - The product is billed once
    • MONTHLY - The product is billed every month
    • QUARTERLY - The product is billed every three months
    • HALF_YEARLY - The product is billed every six months
    • YEARLY - The product is billed every year

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

    One of ONE_TIME MONTHLY QUARTERLY HALF_YEARLY YEARLY

  • accountId string · uuid

    ID of the account for bookkeeping

  • taxCodeId string · uuid

    ID of the tax code

  • avataxCode string

    Avalara tax code

  • discount object

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

    • startDate string · date

    • endDate string · date

    • type string

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

      One of PERCENTAGE AMOUNT

  • quantity number

    Quantity of the product

  • priceOverwrite integer · int64

    Custom price override in cents

    The line total before discount, in the smallest denomination — not a unit price. It stands in for quantity × the product's price, and the unit price Light displays is this figure divided by quantity. null means the line is priced from the product. The model carries no computed amounts (no net, discount or tax figure), so a line's arithmetic is this field, quantity and discount.

  • productNameOverwrite string

    Custom product name override

  • amortizationTemplateId string · uuid

    ID of the amortization template

  • amortizationStartDate string · date

    Start date for amortization

  • amortizationEndDate string · date

    End date for amortization

  • aiValueSuggestions array of object

    AI-generated suggestions for this line

    • field string

    • fieldValues array of string

    • reasoning string

  • 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

  • createdAt string · date-time

    Timestamp when the line was created

  • updatedAt string · date-time

    Timestamp when the line was last updated