Skip to main content
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
}
'
{
  "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

​
billingFrequency
object
required

How often billing should occur for this contract

​
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

​
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

​
contractLimit
object

Optional limit on total contract value or usage

​
advanceConfig
object

Configuration for advance billing or usage adjustments

​
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

Response

200 - application/json

Success

​
error
string
​
message
string
​
data
object