---
title: "Create contract line"
method: POST
path: "/v1/contracts/{contractId}/lines"
tags: ["v1 - Contracts"]
---

# Create contract line

`POST /v1/contracts/{contractId}/lines`

## Request

- Base URL: `https://light.inc` (the document declares no server; this is the origin it was published from)
- URL: `https://light.inc/v1/contracts/{contractId}/lines`
- Auth: one of:
  - API key in header `Authorization`
  - HTTP bearer

Creates a new contract line item

## Path parameters

- `contractId` string, uuid, required

## Headers

- `X-Idempotency-Key` string

## Request body

- ExternalCreateContractLineRequestV1Model
  - `productId` string, uuid: ID of the product
  - `billingStart` string, date, nullable: Date when billing starts for this line
  - `billingEnd` string, date, nullable: Date when billing ends for this line
  - `billingRecurrence` 'ONE_TIME' | 'MONTHLY' | 'QUARTERLY' | 'HALF_YEARLY' | 'YEARLY', nullable: 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.
  - `accountId` string, uuid, nullable: ID of the ledger account for this line
  - `taxCodeId` string, uuid, nullable: ID of the tax code to apply to this line
  - `avataxCode` string, nullable: Avalara tax code. Used when the contract tax engine is AVATAX
  - `discount` ExternalContractLineDiscountV1Model, nullable: Discount to apply to this line (can be percentage or amount-based)
    - `startDate` string, date
    - `endDate` string, date
    - `type` 'PERCENTAGE' | 'AMOUNT': ⚠️ This enum is not exhaustive; new values may be added in the future.
  - `quantity` number, nullable: Quantity of the product
  - `priceOverwrite` integer, nullable: Custom price override in cents
  - `productNameOverwrite` string, nullable: Custom product name override
  - `customProperties` ExternalSetCustomPropertyRequestV1Model[], nullable: List of custom properties to set on the contract or line
    - `groupId` string, uuid: ID of the custom property group.
    - `valueIds` string[]: IDs of the selected custom property values. It behaves as a PUT operation, so if empty the existing ones will be effectively deleted.
    - `inlineValues` string[], nullable: 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.
  - `amortizationTemplateId` string, uuid, nullable: ID of the amortization template
  - `amortizationStartDate` string, date, nullable: Start date for amortization
  - `amortizationEndDate` string, date, nullable: End date for amortization

## Response `default`

default response

- ExternalContractLineV1Model
  - `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, nullable: Date when billing starts for this line
  - `billingEnd` string, date, nullable: Date when billing ends for this line
  - `billingRecurrence` 'ONE_TIME' | 'MONTHLY' | 'QUARTERLY' | 'HALF_YEARLY' | 'YEARLY': 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.
  - `accountId` string, uuid, nullable: ID of the account for bookkeeping
  - `taxCodeId` string, uuid, nullable: ID of the tax code
  - `avataxCode` string, nullable: Avalara tax code
  - `discount` ExternalContractLineDiscountV1Model, nullable: Discount to apply to this line (can be percentage or amount-based)
    - `startDate` string, date
    - `endDate` string, date
    - `type` 'PERCENTAGE' | 'AMOUNT': ⚠️ This enum is not exhaustive; new values may be added in the future.
  - `quantity` number, nullable: Quantity of the product
  - `priceOverwrite` integer, nullable: Custom price override in cents
  - `productNameOverwrite` string, nullable: Custom product name override
  - `amortizationTemplateId` string, uuid, nullable: ID of the amortization template
  - `amortizationStartDate` string, date, nullable: Start date for amortization
  - `amortizationEndDate` string, date, nullable: End date for amortization
  - `aiValueSuggestions` ExternalAiValueSuggestionV1Model[], nullable: AI-generated suggestions for this line
    - `field` string
    - `fieldValues` string[]
    - `reasoning` string
  - `customProperties` ExternalCustomPropertyV1Model[], nullable: 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` ExternalCustomPropertyValueV1Model[]: 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, nullable: 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

---

[API](https://skmtc.dev/light/apis/light-api.md) - [All operations](https://skmtc.dev/light/apis/light-api/llms.txt) - [OpenAPI document](https://skmtc.dev/light/apis/light-api/revisions/84f51306f648?raw)