Create Contracts

cURL

curl --request POST \
  --url https://api.valyx.com/billing/contract \
  --header 'Content-Type: application/json' \
  --header 'X-Valyx-Signature: <x-valyx-signature>' \
  --data '
{
  "customerId": "cust_45678",
  "contractNumber": "CONTRACT-2025-001",
  "contractTitle": "Premium Subscription Plan",
  "contractPeriod": {
    "unit": "MONTH",
    "value": 12
  },
  "billingFrequency": {
    "unit": "MONTH",
    "value": 1
  },
  "isPreusage": false,
  "startDate": "2025-01-01",
  "virtualStartDate": "2025-01-01",
  "creditTermId": "CT-30-DAYS",
  "poNumber": "PO-98765",
  "noteInvoice": "Please pay within 30 days",
  "terms": "Net 30 payment terms apply",
  "noteContract": "This contract is for the premium subscription plan",
  "billingDiscounts": [
    {
      "amount": 100,
      "percentage": 10,
      "isPostTax": false,
      "isUsageBased": false,
      "priority": 1,
      "isStackable": false,
      "tiers": [
        {
          "amount": 50,
          "percentage": 10,
          "isPostTax": false,
          "upTo": 1000
        }
      ],
      "duration": {
        "startIndex": 1,
        "endIndex": 3
      }
    }
  ],
  "billingTime": "BEGINNING_OF_PERIOD",
  "billingReportLimit": {
    "isUsageBased": false,
    "tiers": [
      {
        "upTo": "Infinity",
        "minValue": 123,
        "maxValue": 123
      }
    ],
    "minValue": 123,
    "maxValue": 123
  },
  "contractLimit": {
    "isUsageBased": false,
    "tiers": [
      {
        "upTo": "Infinity",
        "minValue": 123,
        "maxValue": 123
      }
    ],
    "minValue": 123,
    "maxValue": 123
  },
  "advanceConfig": {
    "trueUpEnabled": false,
    "trueDownEnabled": false,
    "actualUsageOverride": false,
    "fileName": "<string>",
    "attachmentId": "<string>"
  },
  "autoRenew": false,
  "renewalPeriod": {
    "value": 123,
    "unit": "MONTH"
  }
}
'

{
  "error": "<string>",
  "message": "<string>",
  "data": {
    "totalDocs": 123,
    "docs": [
      {
        "id": {},
        "customerId": {},
        "contractNumber": {},
        "contractTitle": {},
        "contractPeriod": {},
        "renewalPeriod": {},
        "noteContract": {},
        "billingFrequency": {},
        "usageBillingCycle": {},
        "estimateCycle": {},
        "billingTime": {},
        "startDate": {},
        "virtualStartDate": {},
        "endDate": {},
        "nextBillingDate": {},
        "billingDiscounts": {},
        "isPreusage": {},
        "billingReportLimit": {},
        "contractLimit": {},
        "creditTermId": {},
        "poNumber": {},
        "placeOfSupply": {},
        "billingAddress": {},
        "shippingAddress": {},
        "totalInvoicedAmount": {},
        "noteInvoice": {},
        "terms": {},
        "advanceConfig": {},
        "invoiceSplitConfig": {},
        "gstin": {},
        "companyGstin": {},
        "currency": {},
        "currencyId": {},
        "companyId": {},
        "createdBy": {},
        "updatedBy": {},
        "status": {},
        "autoRenew": {}
      }
    ],
    "hasNext": true,
    "hasPrev": true,
    "pageNumber": 123,
    "pageSize": 123,
    "totalPages": 123,
    "prevPageNumber": 123,
    "nextPageNumber": 123
  }
}

POST

billing

contract

cURL

curl --request POST \
  --url https://api.valyx.com/billing/contract \
  --header 'Content-Type: application/json' \
  --header 'X-Valyx-Signature: <x-valyx-signature>' \
  --data '
{
  "customerId": "cust_45678",
  "contractNumber": "CONTRACT-2025-001",
  "contractTitle": "Premium Subscription Plan",
  "contractPeriod": {
    "unit": "MONTH",
    "value": 12
  },
  "billingFrequency": {
    "unit": "MONTH",
    "value": 1
  },
  "isPreusage": false,
  "startDate": "2025-01-01",
  "virtualStartDate": "2025-01-01",
  "creditTermId": "CT-30-DAYS",
  "poNumber": "PO-98765",
  "noteInvoice": "Please pay within 30 days",
  "terms": "Net 30 payment terms apply",
  "noteContract": "This contract is for the premium subscription plan",
  "billingDiscounts": [
    {
      "amount": 100,
      "percentage": 10,
      "isPostTax": false,
      "isUsageBased": false,
      "priority": 1,
      "isStackable": false,
      "tiers": [
        {
          "amount": 50,
          "percentage": 10,
          "isPostTax": false,
          "upTo": 1000
        }
      ],
      "duration": {
        "startIndex": 1,
        "endIndex": 3
      }
    }
  ],
  "billingTime": "BEGINNING_OF_PERIOD",
  "billingReportLimit": {
    "isUsageBased": false,
    "tiers": [
      {
        "upTo": "Infinity",
        "minValue": 123,
        "maxValue": 123
      }
    ],
    "minValue": 123,
    "maxValue": 123
  },
  "contractLimit": {
    "isUsageBased": false,
    "tiers": [
      {
        "upTo": "Infinity",
        "minValue": 123,
        "maxValue": 123
      }
    ],
    "minValue": 123,
    "maxValue": 123
  },
  "advanceConfig": {
    "trueUpEnabled": false,
    "trueDownEnabled": false,
    "actualUsageOverride": false,
    "fileName": "<string>",
    "attachmentId": "<string>"
  },
  "autoRenew": false,
  "renewalPeriod": {
    "value": 123,
    "unit": "MONTH"
  }
}
'

{
  "error": "<string>",
  "message": "<string>",
  "data": {
    "totalDocs": 123,
    "docs": [
      {
        "id": {},
        "customerId": {},
        "contractNumber": {},
        "contractTitle": {},
        "contractPeriod": {},
        "renewalPeriod": {},
        "noteContract": {},
        "billingFrequency": {},
        "usageBillingCycle": {},
        "estimateCycle": {},
        "billingTime": {},
        "startDate": {},
        "virtualStartDate": {},
        "endDate": {},
        "nextBillingDate": {},
        "billingDiscounts": {},
        "isPreusage": {},
        "billingReportLimit": {},
        "contractLimit": {},
        "creditTermId": {},
        "poNumber": {},
        "placeOfSupply": {},
        "billingAddress": {},
        "shippingAddress": {},
        "totalInvoicedAmount": {},
        "noteInvoice": {},
        "terms": {},
        "advanceConfig": {},
        "invoiceSplitConfig": {},
        "gstin": {},
        "companyGstin": {},
        "currency": {},
        "currencyId": {},
        "companyId": {},
        "createdBy": {},
        "updatedBy": {},
        "status": {},
        "autoRenew": {}
      }
    ],
    "hasNext": true,
    "hasPrev": true,
    "pageNumber": 123,
    "pageSize": 123,
    "totalPages": 123,
    "prevPageNumber": 123,
    "nextPageNumber": 123
  }
}

Headers

X-Valyx-Signature

string

required

Auth key to authenticate the request

Body

application/json

customerId

string

required

The unique identifier of the customer associated with this contract

Example:

"cust_45678"

contractNumber

string

required

A unique reference number for this contract

Example:

"CONTRACT-2025-001"

contractTitle

string

required

The title or name of the contract

Example:

"Premium Subscription Plan"

contractPeriod

object

required

The total duration of the contract, specifying the time unit and value

Show child attributes

contractPeriod.unit

enum<string>

required

The unit of time for the contract period

Available options:

DAY,

WEEK,

MONTH,

YEAR

Example:

"MONTH"

contractPeriod.value

integer

required

The duration of the contract in the specified unit

Example:

12

billingFrequency

object

required

How often billing should occur for this contract

Show child attributes

billingFrequency.unit

enum<string>

required

The unit of time used for billing frequency

Available options:

DAY,

WEEK,

MONTH,

YEAR

Example:

"MONTH"

billingFrequency.value

integer

required

The number of units between each billing cycle

Example:

1

isPreusage

boolean

default:false

required

Indicates if billing should happen at the start of the period (pre-usage)

startDate

string<date>

The date when the contract becomes effective

Example:

"2025-01-01"

virtualStartDate

string<date>

A calculated start date for billing purposes, used if billing time is set to beginning of period

Example:

"2025-01-01"

creditTermId

string

Identifier for the credit term associated with this contract

Example:

"CT-30-DAYS"

poNumber

string

Purchase order number, if applicable

Example:

"PO-98765"

noteInvoice

string

Optional note to be included in the invoice

Example:

"Please pay within 30 days"

terms

string

Terms and conditions associated with this contract

Example:

"Net 30 payment terms apply"

noteContract

string

Optional note to be displayed on the contract

Example:

"This contract is for the premium subscription plan"

billingDiscounts

object[]

List of discounts applicable during billing

Show child attributes

billingDiscounts.amount

number

default:0

required

Fixed discount amount to be applied (in the contract currency). Either amount or percentage should be set.

Example:

100

billingDiscounts.percentage

number

default:0

required

Discount percentage to be applied. Either amount or percentage should be set.

Example:

10

billingDiscounts.isPostTax

boolean

default:false

required

If true, discount is applied after tax calculation; otherwise, before tax.

billingDiscounts.isUsageBased

boolean

default:false

required

Indicates whether this discount is applicable only to usage-based charges.

billingDiscounts.priority

integer

default:1

required

Determines the order in which discounts are applied; lower numbers are applied first.

Example:

1

billingDiscounts.isStackable

boolean

default:false

required

If true, this discount can be combined with other discounts; otherwise, it is exclusive.

billingDiscounts.tiers

object[]

Optional tiered discount levels based on usage.

Show child attributes

billingDiscounts.tiers.amount

number

default:0

required

Fixed discount amount for this tier. Either amount or percentage should be set.

Example:

50

billingDiscounts.tiers.percentage

number

default:0

required

Discount percentage for this tier. Either amount or percentage should be set.

Example:

10

billingDiscounts.tiers.isPostTax

boolean

default:false

required

Indicates if this tiered discount is applied after tax calculation. If false, it is applied before tax.

billingDiscounts.tiers.upTo

number

default:999999999

required

Maximum usage or amount this tier applies to. Use a very large number for no limit.

Example:

1000

billingDiscounts.duration

object

Optional duration specifying the billing periods when this discount is active.

Show child attributes

billingDiscounts.duration.startIndex

integer

required

The starting billing period index when this discount becomes applicable. Indexing starts at 1.

Example:

1

billingDiscounts.duration.endIndex

integer

required

The ending billing period index up to which this discount is applicable.

Example:

3

billingTime

enum<string>

Determines when billing is calculated: either at the beginning of the period or based on subscription start date

Available options:

BEGINNING_OF_PERIOD,

SUBSCRIPTION_DATE

Example:

"BEGINNING_OF_PERIOD"

billingReportLimit

object

Limits applied to the billing report for this contract

Show child attributes

billingReportLimit.isUsageBased

boolean

default:false

required

Indicates if the report limit is based on usage. If true, the tiers and min/max values are interpreted per usage unit.

billingReportLimit.tiers

object[]

Optional list of tiered limits that apply based on usage thresholds.

Show child attributes

billingReportLimit.tiers.upTo

number

default:Infinity

required

The upper limit of this tier. Usage or billing beyond this value will fall into the next tier. Can be set to a very large number to indicate no limit.

billingReportLimit.tiers.minValue

number

The minimum value for this tier. Billing will start counting from this value. Optional if no lower bound is needed.

billingReportLimit.tiers.maxValue

number

The maximum value for this tier. Optional if no upper bound is required.

billingReportLimit.minValue

number

Minimum allowed value for the billing report. Can be omitted if no minimum is required.

billingReportLimit.maxValue

number

Maximum allowed value for the billing report. Can be omitted if no maximum is required.

contractLimit

object

Optional limit on total contract value or usage

Show child attributes

contractLimit.isUsageBased

boolean

default:false

required

Indicates whether the contract limit is usage-based. If true, the system will enforce usage thresholds; otherwise, limits apply to other metrics.

contractLimit.tiers

object[]

A list of tiers defining usage limits for this contract. Each tier can have a min and max value. Optional if the contract has no tiered limits.

Show child attributes

contractLimit.tiers.upTo

number

default:Infinity

required

Defines the upper bound for this tier. All usage up to this value will fall under this tier. Use Infinity for no upper limit.

contractLimit.tiers.minValue

number

The minimum value for this contract tier. Usage or billing calculations start from this threshold.

contractLimit.tiers.maxValue

number

The maximum value for this contract tier. Usage beyond this value will be restricted or handled according to contract rules.

contractLimit.minValue

number

The minimum contract limit value. Billing or usage will start counting from this threshold.

contractLimit.maxValue

number

The maximum contract limit value. Usage beyond this value will be restricted or handled as per contract rules.

advanceConfig

object

Configuration for advance billing or usage adjustments

Show child attributes

advanceConfig.trueUpEnabled

boolean

default:false

Indicates whether true-up adjustments are enabled. True-up allows increasing charges based on actual usage at the end of a billing period.

advanceConfig.trueDownEnabled

boolean

default:false

Indicates whether true-down adjustments are enabled. True-down allows reducing charges based on lower actual usage at the end of a billing period.

advanceConfig.actualUsageOverride

boolean

default:false

If true, allows manually overriding the actual usage for this contract.

advanceConfig.fileName

string

The name of the file uploaded for advance usage configuration, if any.

advanceConfig.attachmentId

string

The ID of the uploaded file stored in the system for reference or download.

autoRenew

boolean

default:false

If true, the contract will automatically renew at the end of its period

renewalPeriod

object

The duration for which the contract should be renewed automatically

Show child attributes

renewalPeriod.value

integer

required

The number of units after which the contract will auto-renew. For example, value=3 and unit=MONTH means the contract renews every 3 months.

renewalPeriod.unit

enum<string>

The time unit for the renewal period. Specifies whether the contract should auto-renew after a number of days, weeks, months, or years.

Available options:

DAY,

WEEK,

MONTH,

YEAR

Example:

"MONTH"

Response

200 - application/json

Success

error

string

message

string

data

object

Show child attributes

data.totalDocs

integer

data.docs

object[]

Show child attributes

data.docs.id

object

data.docs.customerId

object

data.docs.contractNumber

object

data.docs.contractTitle

object

data.docs.contractPeriod

object

data.docs.renewalPeriod

object

data.docs.noteContract

object

data.docs.billingFrequency

object

data.docs.usageBillingCycle

object

data.docs.estimateCycle

object

data.docs.billingTime

object

data.docs.startDate

object

data.docs.virtualStartDate

object

data.docs.endDate

object

data.docs.nextBillingDate

object

data.docs.billingDiscounts

object

data.docs.isPreusage

object

data.docs.billingReportLimit

object

data.docs.contractLimit

object

data.docs.creditTermId

object

data.docs.poNumber

object

data.docs.placeOfSupply

object

data.docs.billingAddress

object

data.docs.shippingAddress

object

data.docs.totalInvoicedAmount

object

data.docs.noteInvoice

object

data.docs.terms

object

data.docs.advanceConfig

object

data.docs.invoiceSplitConfig

object

data.docs.gstin

object

data.docs.companyGstin

object

data.docs.currency

object

data.docs.currencyId

object

data.docs.companyId

object

data.docs.createdBy

object

data.docs.updatedBy

object

data.docs.status

object

data.docs.autoRenew

object

data.hasNext

boolean

data.hasPrev

boolean

data.pageNumber

integer

data.pageSize

integer

data.totalPages

integer

data.prevPageNumber

integer

data.nextPageNumber

integer

API Authentication Filter Contracts

⌘I

Authentication

Billing

Usage

Customer

Invoice

Credit Notes

Examples

Headers

Body

Response