Skip to main content
POST
/
v1
/
contracts
Create contract
curl --request POST \
  --url https://api.light.inc/v1/contracts \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json;charset=UTF-8' \
  --data '
{
  "companyEntityId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "startDate": "2023-12-25",
  "endDate": "2023-12-25",
  "invoiceTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "currency": "USD",
  "estimatedAmount": 123,
  "renewalDate": "2023-12-25",
  "paymentType": "BANK_TRANSFER",
  "payeeBankAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "netTerms": 30,
  "billingStart": "2023-12-25",
  "description": "<string>",
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "areLinesWithTax": true,
  "customProperties": [
    {
      "groupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "valueIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "inlineValues": [
        "<string>"
      ]
    }
  ],
  "lines": [
    {
      "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "billingStart": "2023-12-25",
      "billingEnd": "2023-12-25",
      "billingRecurrence": "ONE_TIME",
      "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "taxCodeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "avataxCode": "<string>",
      "discount": {
        "startDate": "2023-12-25",
        "endDate": "2023-12-25",
        "type": "PERCENTAGE"
      },
      "quantity": 123,
      "priceOverwrite": 123,
      "productNameOverwrite": "<string>",
      "customProperties": [
        {
          "groupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "valueIds": [
            "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          ],
          "inlineValues": [
            "<string>"
          ]
        }
      ],
      "amortizationTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "amortizationStartDate": "2023-12-25",
      "amortizationEndDate": "2023-12-25"
    }
  ]
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "companyId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "startDate": "2023-12-25",
  "endDate": "2023-12-25",
  "activatedAt": "2023-11-07T05:31:56Z",
  "terminatedAt": "2023-11-07T05:31:56Z",
  "terminationReason": "<string>",
  "renewalDate": "2023-12-25",
  "companyEntityId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invoiceTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "currency": "USD",
  "estimatedAmount": 123,
  "paymentType": "BANK_TRANSFER",
  "payeeBankAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "billingStart": "2023-12-25",
  "netTerms": 123,
  "description": "<string>",
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "state": "CREATED",
  "areLinesWithTax": true,
  "lines": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "companyId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "contractId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "billingStart": "2023-12-25",
      "billingEnd": "2023-12-25",
      "billingRecurrence": "ONE_TIME",
      "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "taxCodeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "avataxCode": "<string>",
      "discount": {
        "startDate": "2023-12-25",
        "endDate": "2023-12-25",
        "type": "PERCENTAGE"
      },
      "quantity": 123,
      "priceOverwrite": 123,
      "productNameOverwrite": "<string>",
      "amortizationTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "amortizationStartDate": "2023-12-25",
      "amortizationEndDate": "2023-12-25",
      "aiValueSuggestions": [
        {
          "field": "<string>",
          "fieldValues": [
            "<string>"
          ],
          "reasoning": "<string>"
        }
      ],
      "customProperties": [
        {
          "groupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "groupInternalName": "<string>",
          "values": [
            {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "groupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "groupInternalName": "<string>",
              "companyId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "internalName": "<string>",
              "label": "<string>",
              "context": "<string>",
              "createdAt": "2023-11-07T05:31:56Z",
              "updatedAt": "2023-11-07T05:31:56Z"
            }
          ]
        }
      ],
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "taxEngineName": "AVATAX",
  "externalId": "<string>",
  "externalSource": "HUBSPOT",
  "customProperties": [
    {
      "groupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "groupInternalName": "<string>",
      "values": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "groupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "groupInternalName": "<string>",
          "companyId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "internalName": "<string>",
          "label": "<string>",
          "context": "<string>",
          "createdAt": "2023-11-07T05:31:56Z",
          "updatedAt": "2023-11-07T05:31:56Z"
        }
      ]
    }
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

Basic authentication header of the form Basic <api_key>, where <api_key> is your api key.

Body

application/json;charset=UTF-8
​
companyEntityId
string<uuid>

ID of the company entity

​
startDate
string<date> | null

Contract start date

​
endDate
string<date> | null

Contract end date

​
invoiceTemplateId
string<uuid> | null

ID of the invoice template to use for generating invoices

​
currency
string | null
Example:

"USD"

​
estimatedAmount
integer<int64> | null

Estimated total amount for the contract in cents

​
renewalDate
string<date> | null

Date when the contract should be renewed

​
paymentType
enum<string> | null

Payment type for invoices generated from this contract

  • BANK_TRANSFER - Payment via bank transfer. Bank information 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.

Available options:
BANK_TRANSFER,
STRIPE
​
payeeBankAccountId
string<uuid> | null

ID of the bank account where payments should be sent

​
netTerms
integer<int32> | null
default:30

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

​
billingStart
string<date> | null

Date when billing should start for this contract

​
description
string | null

Description of the contract

​
customerId
string<uuid> | null

ID of the customer

​
areLinesWithTax
boolean
default:true

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

​
customProperties
(object | null)[] | null

List of custom properties to set on the contract or line

List of custom properties to set on the vendor. Replaces the existing set.

​
lines
object[] | null

List of contract line items to create

Response

default - application/json;charset=UTF-8

default response

​
id
string<uuid>

Unique identifier for the object

​
companyId
string<uuid>

ID of the company

​
startDate
string<date> | null

Contract start date

​
endDate
string<date> | null

Contract end date

​
activatedAt
string<date-time> | null

Timestamp when the contract was activated/published

​
terminatedAt
string<date-time> | null

Timestamp when the contract was terminated

​
terminationReason
string | null

Reason for contract termination

​
renewalDate
string<date> | null

Date when the contract should be renewed

​
companyEntityId
string<uuid> | null

ID of the entity

​
invoiceTemplateId
string<uuid> | null

ID of the invoice template to use for generating invoices

​
currency
string
Example:

"USD"

​
estimatedAmount
integer<int64> | null

Estimated total amount for the contract in cents

​
paymentType
enum<string> | null

Payment type for invoices generated from this contract

  • BANK_TRANSFER - Payment via bank transfer. Bank information 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.

Available options:
BANK_TRANSFER,
STRIPE
​
payeeBankAccountId
string<uuid> | null

ID of the bank account where payments should be sent

​
billingStart
string<date> | null

Date when billing should start for this contract

​
netTerms
integer<int32> | null

Number of days from invoice date to when payment is due

​
description
string | null

Description of the contract

​
customerId
string<uuid> | null

ID of the customer

​
state
enum<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
  • TERMINATED - Contract has been terminated

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

Available options:
CREATED,
DRAFT,
ACTIVE,
TERMINATED
​
areLinesWithTax
boolean

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

​
lines
object[] | null

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

​
taxEngineName
enum<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.

Available options:
AVATAX,
LIGHT,
SPHERE
​
externalId
string | null

External identifier from an external system

​
externalSource
enum<string> | null

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.

Available options:
HUBSPOT,
SALESFORCE
​
customProperties
(object | null)[] | null

List of custom properties associated with the contract

Custom properties set on the vendor.

​
createdAt
string<date-time>

Timestamp when the contract was created

​
updatedAt
string<date-time>

Timestamp when the contract was last updated