Light v1 - Contracts API

openapi: 3.2.0
info:
  title: Light v1 - Contracts API
  version: 1.0.0
security:
- apiKeyAuth: []
- bearerAuth: []
tags:
- name: v1 - Contracts
paths:
  /v1/contracts/{contractId}/cancel-termination:
    post:
      tags:
      - v1 - Contracts
      summary: Cancel scheduled termination
      description: Cancels a scheduled termination, returning the contract to active
      operationId: cancelContractTermination
      parameters:
      - name: contractId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalContractV1Model'
  /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.\n\nAvailable directions: `asc`, `desc`. \n\nAvailable 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.\n\nAvailable operators: `eq`, `ne`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`.\n - 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'
    post:
      tags:
      - v1 - Contracts
      summary: Create contract
      description: Creates a new contract
      operationId: createContract
      requestBody:
        content:
          application/json;charset=UTF-8:
            schema:
              $ref: '#/components/schemas/ExternalCreateContractRequestV1Model'
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalContractV1Model'
  /v1/contracts/{contractId}/lines:
    post:
      tags:
      - v1 - Contracts
      summary: Create contract line
      description: Creates a new contract line item
      operationId: createContractLine
      parameters:
      - name: contractId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json;charset=UTF-8:
            schema:
              $ref: '#/components/schemas/ExternalCreateContractLineRequestV1Model'
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalContractLineV1Model'
  /v1/contracts/{contractId}:
    get:
      tags:
      - v1 - Contracts
      summary: Get contract
      description: Returns a specific contract by ID
      operationId: getContract
      parameters:
      - name: contractId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalContractV1Model'
    delete:
      tags:
      - v1 - Contracts
      summary: Delete contract
      description: Deletes a contract by ID
      operationId: deleteContract
      parameters:
      - name: contractId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8: {}
    patch:
      tags:
      - v1 - Contracts
      summary: Update contract
      description: Updates a contract
      operationId: updateContract
      parameters:
      - name: contractId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json;charset=UTF-8:
            schema:
              $ref: '#/components/schemas/ExternalUpdateContractRequestV1Model'
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalContractV1Model'
  /v1/contracts/{contractId}/lines/{lineId}:
    delete:
      tags:
      - v1 - Contracts
      summary: Delete contract line
      description: Deletes a contract line item
      operationId: deleteContractLine
      parameters:
      - name: contractId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: lineId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8: {}
    patch:
      tags:
      - v1 - Contracts
      summary: Update contract line
      description: Updates a contract line item
      operationId: updateContractLine
      parameters:
      - name: contractId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: lineId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json;charset=UTF-8:
            schema:
              $ref: '#/components/schemas/ExternalUpdateContractLineRequestV1Model'
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalContractLineV1Model'
  /v1/contracts/{contractId}/generate-document-upload-url:
    post:
      tags:
      - v1 - Contracts
      summary: Generate document upload URL
      description: Generates a pre-signed URL to upload the main contract document (PDF). After uploading to this URL, the document will appear in the contract's document preview.
      operationId: generateContractDocumentUploadUrl
      parameters:
      - name: contractId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json;charset=UTF-8:
            schema:
              $ref: '#/components/schemas/ExternalContractDocumentUploadRequestV1Model'
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalContractDocumentUploadUrlResponseV1Model'
  /v1/contracts/{contractId}/publish:
    post:
      tags:
      - v1 - Contracts
      summary: Publish contract
      description: Publishes a contract, transitioning it to ACTIVE state
      operationId: publishContract
      parameters:
      - name: contractId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalContractV1Model'
  /v1/contracts/{contractId}/renew:
    post:
      tags:
      - v1 - Contracts
      summary: Renew contract
      description: Renews a contract by extending its end date
      operationId: renewContract
      parameters:
      - name: contractId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json;charset=UTF-8:
            schema:
              $ref: '#/components/schemas/ExternalRenewContractRequestV1Model'
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalContractV1Model'
  /v1/contracts/{contractId}/reset:
    post:
      tags:
      - v1 - Contracts
      summary: Reset contract
      description: Resets a contract to CREATED state
      operationId: resetContract
      parameters:
      - name: contractId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalContractV1Model'
  /v1/contracts/{contractId}/terminate:
    post:
      tags:
      - v1 - Contracts
      summary: Terminate contract
      description: Terminates a contract
      operationId: terminateContract
      parameters:
      - name: contractId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json;charset=UTF-8:
            schema:
              $ref: '#/components/schemas/ExternalTerminateContractRequestV1Model'
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ExternalContractV1Model'
components:
  schemas:
    ExternalCreateContractLineRequestV1Model:
      type: object
      properties:
        productId:
          type: string
          description: ID of the product
          format: uuid
        billingStart:
          type:
          - string
          - 'null'
          description: Date when billing starts for this line
          format: date
        billingEnd:
          type:
          - string
          - 'null'
          description: Date when billing ends for this line
          format: date
        billingRecurrence:
          type:
          - string
          - 'null'
          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.'
          deprecated: false
          enum:
          - ONE_TIME
          - MONTHLY
          - QUARTERLY
          - HALF_YEARLY
          - YEARLY
        accountId:
          type:
          - string
          - 'null'
          description: ID of the ledger account for this line
          format: uuid
        taxCodeId:
          type:
          - string
          - 'null'
          description: ID of the tax code to apply to this line
          format: uuid
        avataxCode:
          type:
          - string
          - 'null'
          description: Avalara tax code. Used when the contract tax engine is AVATAX
        discount:
          $ref: '#/components/schemas/ExternalContractLineDiscountV1Model'
        quantity:
          type:
          - number
          - 'null'
          description: Quantity of the product
        priceOverwrite:
          type:
          - integer
          - 'null'
          description: Custom price override in cents
          format: int64
        productNameOverwrite:
          type:
          - string
          - 'null'
          description: Custom product name override
        customProperties:
          type:
          - array
          - 'null'
          description: List of custom properties to set on the contract or line
          items:
            $ref: '#/components/schemas/ExternalSetCustomPropertyRequestV1Model'
        amortizationTemplateId:
          type:
          - string
          - 'null'
          description: ID of the amortization template
          format: uuid
        amortizationStartDate:
          type:
          - string
          - 'null'
          description: Start date for amortization
          format: date
        amortizationEndDate:
          type:
          - string
          - 'null'
          description: End date for amortization
          format: date
    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
          - 'null'
          description: Contract start date
          format: date
        endDate:
          type:
          - string
          - 'null'
          description: Contract end date
          format: date
        activatedAt:
          type:
          - string
          - 'null'
          description: Timestamp when the contract was activated/published
          format: date-time
        terminatedAt:
          type:
          - string
          - 'null'
          description: Timestamp when the contract was terminated
          format: date-time
        terminationReason:
          type:
          - string
          - 'null'
          description: Reason for contract termination
        renewalDate:
          type:
          - string
          - 'null'
          description: Date when the contract should be renewed
          format: date
        companyEntityId:
          type:
          - string
          - 'null'
          description: ID of the entity
          format: uuid
        invoiceTemplateId:
          type:
          - string
          - 'null'
          description: ID of the invoice template to use for generating invoices
          format: uuid
        currency:
          type: string
          example: USD
        estimatedAmount:
          type:
          - integer
          - 'null'
          description: Estimated total amount for the contract in cents
          format: int64
        paymentType:
          type:
          - string
          - 'null'
          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.'
          deprecated: false
          enum:
          - AIRWALLEX
          - BANK_TRANSFER
          - DIRECT_DEBIT
          - STRIPE
        payeeBankAccountId:
          type:
          - string
          - 'null'
          description: ID of the bank account where payments should be sent
          format: uuid
        billingStart:
          type:
          - string
          - 'null'
          description: Date when billing should start for this contract
          format: date
        netTerms:
          type:
          - integer
          - 'null'
          description: Number of days from invoice date to when payment is due
          format: int32
        invoiceLeadDays:
          type:
          - integer
          - 'null'
          description: Number of days before billing period start to date the invoice
          format: int32
        description:
          type:
          - string
          - 'null'
          description: Description of the contract
        customerId:
          type:
          - string
          - 'null'
          description: ID of the customer
          format: uuid
        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.'
          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
          - 'null'
          description: List of contract line items. Only returned when fetching a single contract by ID
          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.'
          deprecated: false
          enum:
          - AVATAX
          - LIGHT
          - SPHERE
        externalId:
          type:
          - string
          - 'null'
          description: External identifier from an external system
        externalSource:
          type:
          - string
          - 'null'
          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.'
          deprecated: false
          enum:
          - HUBSPOT
          - SALESFORCE
        customProperties:
          type:
          - array
          - 'null'
          description: List of custom properties associated with the contract
          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
    ExternalCreateContractRequestV1Model:
      type: object
      properties:
        companyEntityId:
          type: string
          description: ID of the company entity
          format: uuid
        startDate:
          type:
          - string
          - 'null'
          description: Contract start date
          format: date
        endDate:
          type:
          - string
          - 'null'
          description: Contract end date
          format: date
        invoiceTemplateId:
          type:
          - string
          - 'null'
          description: ID of the invoice template to use for generating invoices
          format: uuid
        currency:
          type:
          - string
          - 'null'
          example: USD
        estimatedAmount:
          type:
          - integer
          - 'null'
          description: Estimated total amount for the contract in cents
          format: int64
        renewalDate:
          type:
          - string
          - 'null'
          description: Date when the contract should be renewed
          format: date
        paymentType:
          type:
          - string
          - 'null'
          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.'
          deprecated: false
          enum:
          - AIRWALLEX
          - BANK_TRANSFER
          - DIRECT_DEBIT
          - STRIPE
        payeeBankAccountId:
          type:
          - string
          - 'null'
          description: ID of the bank account where payments should be sent
          format: uuid
        netTerms:
          type:
          - integer
          - 'null'
          description: Number of days from invoice date to when payment is due. Defaults to 30
          format: int32
          default: 30
        invoiceLeadDays:
          type:
          - integer
          - 'null'
          description: Number of days before the billing period start to date the invoice. Defaults to 0
          format: int32
          default: 0
        billingStart:
          type:
          - string
          - 'null'
          description: Date when billing should start for this contract
          format: date
        description:
          type:
          - string
          - 'null'
          description: Description of the contract
        customerId:
          type:
          - string
          - 'null'
          description: ID of the customer
          format: uuid
        areLinesWithTax:
          type: boolean
          description: Whether invoice line amounts include tax or tax is added on top. Defaults to true
          default: true
        customProperties:
          type:
          - array
          - 'null'
          description: List of custom properties to set on the contract or line
          items:
            $ref: '#/components/schemas/ExternalSetCustomPropertyRequestV1Model'
        lines:
          type:
          - array
          - 'null'
          description: List of contract line items to create
          items:
            $ref: '#/components/schemas/ExternalCreateContractLineRequestV1Model'
    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
          - 'null'
          description: Date when billing starts for this line
          format: date
        billingEnd:
          type:
          - string
          - 'null'
          description: Date when billing ends for this line
          format: date
        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.'
          deprecated: false
          enum:
          - ONE_TIME
          - MONTHLY
          - QUARTERLY
          - HALF_YEARLY
          - YEARLY
        accountId:
          type:
          - string
          - 'null'
          description: ID of the account for bookkeeping
          format: uuid
        taxCodeId:
          type:
          - string
          - 'null'
          description: ID of the tax code
          format: uuid
        avataxCode:
          type:
          - string
          - 'null'
          description: Avalara tax code
        discount:
          $ref: '#/components/schemas/ExternalContractLineDiscountV1Model'
        quantity:
          type:
          - number
          - 'null'
          description: Quantity of the product
        priceOverwrite:
          type:
          - integer
          - 'null'
          description: Custom price override in cents
          format: int64
        productNameOverwrite:
          type:
          - string
          - 'null'
          description: Custom product name override
        amortizationTemplateId:
          type:
          - string
          - 'null'
          description: ID of the amortization template
          format: uuid
        amortizationStartDate:
          type:
          - string
          - 'null'
          description: Start date for amortization
          format: date
        amortizationEndDate:
          type:
          - string
          - 'null'
          description: End date for amortization
          format: date
        aiValueSuggestions:
          type:
          - array
          - 'null'
          description: AI-generated suggestions for this line
          items:
            $ref: '#/components/schemas/ExternalAiValueSuggestionV1Model'
        customProperties:
          type:
          - array
          - 'null'
          description: List of custom properties associated with the line
          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
    ExternalContractDocumentUploadRequestV1Model:
      type: object
      properties:
        filename:
          type: string
          description: Name of the file to upload
    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
          - 'null'
          description: Context/description of the custom property value
        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
    ExternalUpdateContractLineRequestV1Model:
      type: object
      properties:
        productId:
          type:
          - string
          - 'null'
          description: ID of the product
          format: uuid
        billingStart:
          type:
          - string
          - 'null'
          description: Date when billing starts for this line
          format: date
        accountId:
          type:
          - string
          - 'null'
          description: ID of the ledger account for this line
          format: uuid
        taxCodeId:
          type:
          - string
          - 'null'
          description: ID of the tax code to apply to this line
          format: uuid
        customProperties:
          type:
          - array
          - 'null'
          description: List of custom properties to set on the contract or line
          items:
            $ref: '#/components/schemas/ExternalSetCustomPropertyRequestV1Model'
        billingRecurrence:
          type:
          - string
          - 'null'
          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.'
          deprecated: false
          enum:
          - ONE_TIME
          - MONTHLY
          - QUARTERLY
          - HALF_YEARLY
          - YEARLY
        billingEnd:
          type:
          - string
          - 'null'
          description: Date when billing ends for this line
          format: date
        discount:
          $ref: '#/components/schemas/ExternalContractLineDiscountV1Model'
        priceOverwrite:
          type:
          - integer
          - 'null'
          description: Custom price override in cents
          format: int64
        productNameOverwrite:
          type:
          - string
          - 'null'
          description: Custom product name override
        quantity:
          type:
          - number
          - 'null'
          description: Quantity of the product
        amortizationTemplateId:
          type:
          - string
          - 'null'
          description: ID of the amortization template
          format: uuid
        amortizationStartDate:
          type:
          - string
          - 'null'
          description: Start date for amortization
          format: date
        amortizationEndDate:
          type:
          - string
          - 'null'
          description: End date for amortization
          format: date
    ExternalAiValueSuggestionV1Model:
      type:
      - object
      - 'null'
      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).
    ExternalContractDocumentUploadUrlResponseV1Model:
      type: object
      properties:
        uploadUrl:
          type: string
          description: Pre-signed URL to upload the document to
        key:
          type: string
          description: Key to identify the uploaded document
        metadata:
          type:
          - object
          - 'n

# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/light/refs/heads/main/openapi/light-v1-contracts-api-openapi.yml