Light APIv1.0.0

API / Reference / Contracts

Create contract

POST https://api.light.inc/v1/contracts

Creates a new contract

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

Headers

  • X-Idempotency-Key string

Request body

application/json;charset=UTF-8

  • companyEntityId string · uuid

    ID of the company entity

  • startDate string · date

    Contract start date

  • endDate string · date

    Contract end date

  • invoiceTemplateId string · uuid

    ID of the invoice template to use for generating invoices

  • currency string

  • estimatedAmount integer · int64

    Estimated total amount for the contract in cents

  • renewalDate string · date

    Date when the contract should be renewed

  • paymentType string

    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.

    One of AIRWALLEX BANK_TRANSFER DIRECT_DEBIT STRIPE

  • payeeBankAccountId string · uuid

    ID of the bank account where payments should be sent

  • netTerms integer · int32

    Number of days from invoice date to when payment is due. Defaults to 30

  • invoiceLeadDays integer · int32

    Number of days before the billing period start to date the invoice. Defaults to 0

  • billingStart string · date

    Date when billing should start for this contract

  • description string

    Description of the contract

  • customerId string · uuid

    ID of the customer

  • areLinesWithTax boolean

    Whether invoice line amounts include tax or tax is added on top. Defaults to true

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

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

  • lines array of object

    List of contract line items to create

    • 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

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

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

    • 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

  • startDate string · date

    Contract start date

  • endDate string · date

    Contract end date

  • activatedAt string · date-time

    Timestamp when the contract was activated/published

  • terminatedAt string · date-time

    Timestamp when the contract was terminated

  • terminationReason string

    Reason for contract termination

  • terminationReasonType string

    Categorized reason for contract termination

    • FINISHED - Contract ran to its natural end
    • OTHER - Terminated for another reason, described in terminationReason
    • RENEWED - Contract ended because it was renewed into a new contract

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

    One of FINISHED OTHER RENEWED

  • renewalDate string · date

    Date when the contract should be renewed

  • companyEntityId string · uuid

    ID of the entity

  • invoiceTemplateId string · uuid

    ID of the invoice template to use for generating invoices

  • currency string

  • estimatedAmount integer · int64

    Estimated total amount for the contract in cents

  • paymentType string

    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.

    One of AIRWALLEX BANK_TRANSFER DIRECT_DEBIT STRIPE

  • payeeBankAccountId string · uuid

    ID of the bank account where payments should be sent

  • billingStart string · date

    Date when billing should start for this contract

  • netTerms integer · int32

    Number of days from invoice date to when payment is due

  • invoiceLeadDays integer · int32

    Number of days before billing period start to date the invoice

  • description string

    Description of the contract

  • customerId string · uuid

    ID of the customer

  • state string

    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.

    One of CREATED DRAFT ACTIVE PENDING_TERMINATION TERMINATED

  • areLinesWithTax boolean

    Whether invoice line amounts include tax or tax is added on top

  • lines array of object

    List of contract line items. Only returned when fetching a single contract by ID

    • 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

    • 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

  • taxEngineName string

    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.

    One of AVATAX LIGHT SPHERE

  • externalId string

    External identifier from an external system

  • externalSource string

    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.

    One of HUBSPOT SALESFORCE

  • customProperties array of object

    List of custom properties associated with the contract

    • 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 contract was created

  • updatedAt string · date-time

    Timestamp when the contract was last updated