> ## Documentation Index
> Fetch the complete documentation index at: https://docs.light.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# List contracts

> Returns a paginated list of contracts



## OpenAPI

````yaml /openapi-public.json get /v1/contracts
openapi: 3.0.1
info:
  title: Light API
  version: 1.0.0
servers: []
security:
  - apiKeyAuth: []
  - bearerAuth: []
paths:
  /v1/contracts:
    get:
      tags:
        - v1 - Contracts
      summary: List contracts
      description: Returns a paginated list of contracts
      operationId: listContracts
      parameters:
        - name: sort
          in: query
          schema:
            type: string
            description: >-
              Sort string in the format `field:direction`. To provide multiple
              sort fields, separate them with commas.


              Available directions: `asc`, `desc`. 


              Available fields: `activatedAt`, `companyEntityId`,
              `companyEntityName`, `createdAt`, `customerId`, `customerName`,
              `description`, `endDate`, `estimatedAmount`, `renewalDate`,
              `startDate`, `state`, `terminatedAt`.
            example: amount:desc,createdAt:asc
        - name: filter
          in: query
          schema:
            type: string
            description: >-
              Filter string in the format `field:operator:value`. To provide
              multiple filters, separate them with commas.


              Available operators: `eq`, `ne`, `in`, `not_in`, `gt`, `gte`,
              `lt`, `lte`.
               - For `in` and `not_in` operators, provide multiple values separated by the pipe character (`|`).
            example: state:in:IN_DRAFT|SCHEDULED|PAID,amount:gte:500,vendorId:ne:null
        - name: limit
          in: query
          description: Maximum number of items to return. Default is 50, maximum is 200.
          schema:
            maximum: 200
            type: integer
            format: int32
        - name: offset
          in: query
          description: >-
            Number of items to skip before starting to collect the result set.
            Deprecated, use 'cursor' instead.
          deprecated: true
          schema:
            type: integer
            format: int64
        - name: cursor
          in: query
          description: >-
            The cursor position to start returning results from.

            To opt-in into cursor-based pagination, provide `0` for the initial
            request.

            For subsequent requests, use `nextCursor` and `prevCursor` from the
            previous response to navigate.

            Cursor values are opaque and should not be constructed manually.
          schema:
            type: string
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: >-
                  #/components/schemas/ExternalPaginatedResponseV1ModelExternalContractV1Model
components:
  schemas:
    ExternalPaginatedResponseV1ModelExternalContractV1Model:
      type: object
      properties:
        records:
          type: array
          description: List of records for the current page
          items:
            $ref: '#/components/schemas/ExternalContractV1Model'
        hasMore:
          type: boolean
          description: Boolean flag indicating if there are more records available
        total:
          type: integer
          description: >-
            Total number of records (only for offset pagination). This field is
            not guaranteed to be returned and only available for offset
            pagination, please do not rely on it and migrate to cursor
            pagination.
          format: int64
          nullable: true
          deprecated: true
        nextCursor:
          type: string
          description: Cursor for fetching the next page (only for cursor pagination)
          nullable: true
        prevCursor:
          type: string
          description: Cursor for fetching the previous page (only for cursor pagination)
          nullable: true
    ExternalContractV1Model:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the object
          format: uuid
        companyId:
          type: string
          description: ID of the company
          format: uuid
        startDate:
          type: string
          description: Contract start date
          format: date
          nullable: true
        endDate:
          type: string
          description: Contract end date
          format: date
          nullable: true
        activatedAt:
          type: string
          description: Timestamp when the contract was activated/published
          format: date-time
          nullable: true
        terminatedAt:
          type: string
          description: Timestamp when the contract was terminated
          format: date-time
          nullable: true
        terminationReason:
          type: string
          description: Reason for contract termination
          nullable: true
        renewalDate:
          type: string
          description: Date when the contract should be renewed
          format: date
          nullable: true
        companyEntityId:
          type: string
          description: ID of the entity
          format: uuid
          nullable: true
        invoiceTemplateId:
          type: string
          description: ID of the invoice template to use for generating invoices
          format: uuid
          nullable: true
        currency:
          type: string
          example: USD
        estimatedAmount:
          type: integer
          description: Estimated total amount for the contract in cents
          format: int64
          nullable: true
        paymentType:
          type: string
          description: >-
            Payment type for invoices generated from this contract


            - `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.
          nullable: true
          deprecated: false
          enum:
            - AIRWALLEX
            - BANK_TRANSFER
            - DIRECT_DEBIT
            - STRIPE
        payeeBankAccountId:
          type: string
          description: ID of the bank account where payments should be sent
          format: uuid
          nullable: true
        billingStart:
          type: string
          description: Date when billing should start for this contract
          format: date
          nullable: true
        netTerms:
          type: integer
          description: Number of days from invoice date to when payment is due
          format: int32
          nullable: true
        invoiceLeadDays:
          type: integer
          description: Number of days before billing period start to date the invoice
          format: int32
          nullable: true
        description:
          type: string
          description: Description of the contract
          nullable: true
        customerId:
          type: string
          description: ID of the customer
          format: uuid
          nullable: true
        state:
          type: string
          description: >-
            Current state of the contract


            - `CREATED` - Contract has been created

            - `DRAFT` - Contract is in draft state and can be edited

            - `ACTIVE` - Contract is active and generating invoices

            - `PENDING_TERMINATION` - Contract has a scheduled termination

            - `TERMINATED` - Contract has been terminated


            ⚠️ This enum is not exhaustive; new values may be added in the
            future.
          nullable: false
          deprecated: false
          enum:
            - CREATED
            - DRAFT
            - ACTIVE
            - PENDING_TERMINATION
            - TERMINATED
        areLinesWithTax:
          type: boolean
          description: Whether invoice line amounts include tax or tax is added on top
        lines:
          type: array
          description: >-
            List of contract line items. Only returned when fetching a single
            contract by ID
          nullable: true
          items:
            $ref: '#/components/schemas/ExternalContractLineV1Model'
        taxEngineName:
          type: string
          description: >-
            Name of the tax engine to be used


            - `AVATAX` - Avalara AvaTax will be used for tax calculations

            - `LIGHT` - Light built-in tax engine will be used for tax
            calculations

            - `SPHERE` - Sphere tax engine will be used for tax calculations


            ⚠️ This enum is not exhaustive; new values may be added in the
            future.
          nullable: false
          deprecated: false
          enum:
            - AVATAX
            - LIGHT
            - SPHERE
        externalId:
          type: string
          description: External identifier from an external system
          nullable: true
        externalSource:
          type: string
          description: >-
            Source system if contract was synced from an external system


            - `HUBSPOT` - Contract synced from HubSpot

            - `SALESFORCE` - Contract synced from Salesforce


            ⚠️ This enum is not exhaustive; new values may be added in the
            future.
          nullable: true
          deprecated: false
          enum:
            - HUBSPOT
            - SALESFORCE
        customProperties:
          type: array
          description: List of custom properties associated with the contract
          nullable: true
          items:
            $ref: '#/components/schemas/ExternalCustomPropertyV1Model'
        createdAt:
          type: string
          description: Timestamp when the contract was created
          format: date-time
        updatedAt:
          type: string
          description: Timestamp when the contract was last updated
          format: date-time
    ExternalContractLineV1Model:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the object
          format: uuid
        companyId:
          type: string
          description: ID of the company
          format: uuid
        contractId:
          type: string
          description: ID of the contract this line belongs to
          format: uuid
        productId:
          type: string
          description: ID of the product
          format: uuid
        billingStart:
          type: string
          description: Date when billing starts for this line
          format: date
          nullable: true
        billingEnd:
          type: string
          description: Date when billing ends for this line
          format: date
          nullable: true
        billingRecurrence:
          type: string
          description: >-
            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.
          nullable: false
          deprecated: false
          enum:
            - ONE_TIME
            - MONTHLY
            - QUARTERLY
            - HALF_YEARLY
            - YEARLY
        accountId:
          type: string
          description: ID of the account for bookkeeping
          format: uuid
          nullable: true
        taxCodeId:
          type: string
          description: ID of the tax code
          format: uuid
          nullable: true
        avataxCode:
          type: string
          description: Avalara tax code
          nullable: true
        discount:
          $ref: '#/components/schemas/ExternalContractLineDiscountV1Model'
        quantity:
          type: number
          description: Quantity of the product
          nullable: true
        priceOverwrite:
          type: integer
          description: Custom price override in cents
          format: int64
          nullable: true
        productNameOverwrite:
          type: string
          description: Custom product name override
          nullable: true
        amortizationTemplateId:
          type: string
          description: ID of the amortization template
          format: uuid
          nullable: true
        amortizationStartDate:
          type: string
          description: Start date for amortization
          format: date
          nullable: true
        amortizationEndDate:
          type: string
          description: End date for amortization
          format: date
          nullable: true
        aiValueSuggestions:
          type: array
          description: AI-generated suggestions for this line
          nullable: true
          items:
            $ref: '#/components/schemas/ExternalAiValueSuggestionV1Model'
        customProperties:
          type: array
          description: List of custom properties associated with the line
          nullable: true
          items:
            $ref: '#/components/schemas/ExternalCustomPropertyV1Model'
        createdAt:
          type: string
          description: Timestamp when the line was created
          format: date-time
        updatedAt:
          type: string
          description: Timestamp when the line was last updated
          format: date-time
    ExternalCustomPropertyV1Model:
      type: object
      properties:
        groupId:
          type: string
          description: ID of the custom property group
          format: uuid
        groupInternalName:
          type: string
          description: Internal name of the custom property group
        values:
          type: array
          description: >-
            List of values. Note that this will be a single value unless the
            group input type supports multiple values
          items:
            $ref: '#/components/schemas/ExternalCustomPropertyValueV1Model'
      description: Custom properties set on the vendor.
      nullable: true
    ExternalContractLineDiscountV1Model:
      type: object
      properties:
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        type:
          type: string
          description: >-
            ⚠️ This enum is not exhaustive; new values may be added in the
            future.
          enum:
            - PERCENTAGE
            - AMOUNT
      description: Discount to apply to this line (can be percentage or amount-based)
      nullable: true
      discriminator:
        propertyName: type
    ExternalAiValueSuggestionV1Model:
      type: object
      properties:
        field:
          type: string
        fieldValues:
          type: array
          items:
            type: string
        reasoning:
          type: string
      description: >-
        AI-generated suggestions for line item values (e.g. account, cost
        center, tax code).
      nullable: true
    ExternalCustomPropertyValueV1Model:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the object
          format: uuid
        groupId:
          type: string
          description: ID of the custom property group
          format: uuid
        groupInternalName:
          type: string
          description: Internal name of the custom property group
        companyId:
          type: string
          description: ID of the company
          format: uuid
        internalName:
          type: string
          description: Internal name of the custom property value
        label:
          type: string
          description: Label of the custom property value
        context:
          type: string
          description: Context/description of the custom property value
          nullable: true
        createdAt:
          type: string
          description: Timestamp when the custom property value was created
          format: date-time
        updatedAt:
          type: string
          description: Timestamp when the custom property value was last updated
          format: date-time
      description: >-
        List of values. Note that this will be a single value unless the group
        input type supports multiple values
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      description: >-
        Basic authentication header of the form **Basic** **<api_key>**, where
        **<api_key>** is your api key.
      name: Authorization
      in: header
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````