> ## Documentation Index > Fetch the complete documentation index at: https://docs.valyx.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Contracts ## OpenAPI ````yaml POST /billing/contract openapi: 3.1.0 info: title: OpenAPI Valyx API description: To demonstrate features in the Valyx license: name: MIT version: 1.0.0 servers: - url: https://api.valyx.com security: - bearerAuth: - demo-api tags: - name: billing description: External Billing APIs - name: external description: External APIs for customers - name: invoice description: Invoice APIs - name: creditNote description: Credit Note APIs paths: /billing/contract: parameters: - name: X-Valyx-Signature in: header required: true description: Auth key to authenticate the request schema: type: string post: tags: - billing operationId: post_create_contract requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateContractAPIRequestModel' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ContractResponseModel' components: schemas: CreateContractAPIRequestModel: type: object required: - contractNumber - contractTitle - customerId - isPreusage - contractPeriod - billingFrequency properties: customerId: type: string description: The unique identifier of the customer associated with this contract example: cust_45678 contractNumber: type: string description: A unique reference number for this contract example: CONTRACT-2025-001 contractTitle: type: string description: The title or name of the contract example: Premium Subscription Plan contractPeriod: $ref: '#/components/schemas/CreateContractAPIRequestModelcontractPeriod' description: >- The total duration of the contract, specifying the time unit and value billingFrequency: $ref: '#/components/schemas/CreateContractAPIRequestModelbillingFrequency' description: How often billing should occur for this contract startDate: type: string format: date description: The date when the contract becomes effective example: '2025-01-01' virtualStartDate: type: string format: date description: >- A calculated start date for billing purposes, used if billing time is set to beginning of period example: '2025-01-01' creditTermId: type: string description: Identifier for the credit term associated with this contract example: CT-30-DAYS poNumber: type: string description: Purchase order number, if applicable example: PO-98765 noteInvoice: type: string description: Optional note to be included in the invoice example: Please pay within 30 days terms: type: string description: Terms and conditions associated with this contract example: Net 30 payment terms apply noteContract: type: string description: Optional note to be displayed on the contract example: This contract is for the premium subscription plan billingDiscounts: type: array description: List of discounts applicable during billing items: $ref: '#/components/schemas/CreateContractAPIRequestModelbillingDiscounts' isPreusage: type: boolean description: >- Indicates if billing should happen at the start of the period (pre-usage) default: false billingTime: type: string description: >- Determines when billing is calculated: either at the beginning of the period or based on subscription start date example: BEGINNING_OF_PERIOD enum: - BEGINNING_OF_PERIOD - SUBSCRIPTION_DATE billingReportLimit: $ref: '#/components/schemas/CreateContractAPIRequestModelbillingReportLimit' description: Limits applied to the billing report for this contract contractLimit: $ref: '#/components/schemas/CreateContractAPIRequestModelcontractLimit' description: Optional limit on total contract value or usage advanceConfig: $ref: '#/components/schemas/CreateContractAPIRequestModeladvanceConfig' description: Configuration for advance billing or usage adjustments autoRenew: type: boolean description: >- If true, the contract will automatically renew at the end of its period default: false renewalPeriod: $ref: '#/components/schemas/CreateContractAPIRequestModelrenewalPeriod' description: The duration for which the contract should be renewed automatically ContractResponseModel: properties: error: type: string message: type: string data: $ref: '#/components/schemas/ContractPaginatedResponseModel' type: object CreateContractAPIRequestModelcontractPeriod: type: object required: - value - unit properties: unit: type: string description: The unit of time for the contract period example: MONTH enum: - DAY - WEEK - MONTH - YEAR value: type: integer description: The duration of the contract in the specified unit example: 12 CreateContractAPIRequestModelbillingFrequency: type: object required: - value - unit properties: unit: type: string description: The unit of time used for billing frequency example: MONTH enum: - DAY - WEEK - MONTH - YEAR value: type: integer description: The number of units between each billing cycle example: 1 CreateContractAPIRequestModelbillingDiscounts: type: object required: - amount - percentage - isPostTax - isUsageBased - priority - isStackable properties: amount: type: number description: >- Fixed discount amount to be applied (in the contract currency). Either amount or percentage should be set. default: 0 example: 100 percentage: type: number description: >- Discount percentage to be applied. Either amount or percentage should be set. default: 0 example: 10 isPostTax: type: boolean description: >- If true, discount is applied after tax calculation; otherwise, before tax. default: false isUsageBased: type: boolean description: >- Indicates whether this discount is applicable only to usage-based charges. default: false tiers: type: array description: Optional tiered discount levels based on usage. items: $ref: >- #/components/schemas/CreateContractAPIRequestModelbillingDiscountstiers priority: type: integer description: >- Determines the order in which discounts are applied; lower numbers are applied first. default: 1 example: 1 isStackable: type: boolean description: >- If true, this discount can be combined with other discounts; otherwise, it is exclusive. default: false duration: $ref: >- #/components/schemas/CreateContractAPIRequestModelbillingDiscountsduration description: >- Optional duration specifying the billing periods when this discount is active. CreateContractAPIRequestModelbillingReportLimit: type: object required: - isUsageBased properties: tiers: type: array description: Optional list of tiered limits that apply based on usage thresholds. items: $ref: >- #/components/schemas/CreateContractAPIRequestModelbillingReportLimittiers isUsageBased: type: boolean description: >- Indicates if the report limit is based on usage. If true, the tiers and min/max values are interpreted per usage unit. default: false minValue: type: number description: >- Minimum allowed value for the billing report. Can be omitted if no minimum is required. maxValue: type: number description: >- Maximum allowed value for the billing report. Can be omitted if no maximum is required. CreateContractAPIRequestModelcontractLimit: type: object required: - isUsageBased properties: tiers: type: array description: >- 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. items: $ref: >- #/components/schemas/CreateContractAPIRequestModelcontractLimittiers isUsageBased: type: boolean description: >- Indicates whether the contract limit is usage-based. If true, the system will enforce usage thresholds; otherwise, limits apply to other metrics. default: false minValue: type: number description: >- The minimum contract limit value. Billing or usage will start counting from this threshold. maxValue: type: number description: >- The maximum contract limit value. Usage beyond this value will be restricted or handled as per contract rules. CreateContractAPIRequestModeladvanceConfig: type: object properties: trueUpEnabled: type: boolean description: >- Indicates whether true-up adjustments are enabled. True-up allows increasing charges based on actual usage at the end of a billing period. default: false trueDownEnabled: type: boolean description: >- Indicates whether true-down adjustments are enabled. True-down allows reducing charges based on lower actual usage at the end of a billing period. default: false actualUsageOverride: type: boolean description: >- If true, allows manually overriding the actual usage for this contract. default: false fileName: type: string description: >- The name of the file uploaded for advance usage configuration, if any. attachmentId: type: string description: >- The ID of the uploaded file stored in the system for reference or download. CreateContractAPIRequestModelrenewalPeriod: type: object required: - value properties: unit: type: string description: >- The time unit for the renewal period. Specifies whether the contract should auto-renew after a number of days, weeks, months, or years. example: MONTH enum: - DAY - WEEK - MONTH - YEAR value: type: integer description: >- 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. ContractPaginatedResponseModel: properties: totalDocs: type: integer docs: type: array items: $ref: '#/components/schemas/ContractData' hasNext: type: boolean hasPrev: type: boolean pageNumber: type: integer pageSize: type: integer totalPages: type: integer prevPageNumber: type: integer nextPageNumber: type: integer type: object CreateContractAPIRequestModelbillingDiscountstiers: type: object required: - amount - percentage - isPostTax - upTo properties: amount: type: number description: >- Fixed discount amount for this tier. Either amount or percentage should be set. default: 0 example: 50 percentage: type: number description: >- Discount percentage for this tier. Either amount or percentage should be set. default: 0 example: 10 isPostTax: type: boolean description: >- Indicates if this tiered discount is applied after tax calculation. If false, it is applied before tax. default: false upTo: type: number description: >- Maximum usage or amount this tier applies to. Use a very large number for no limit. default: 999999999 example: 1000 CreateContractAPIRequestModelbillingDiscountsduration: type: object required: - startIndex - endIndex properties: startIndex: type: integer description: >- The starting billing period index when this discount becomes applicable. Indexing starts at 1. example: 1 endIndex: type: integer description: >- The ending billing period index up to which this discount is applicable. example: 3 CreateContractAPIRequestModelbillingReportLimittiers: type: object required: - upTo properties: minValue: type: number description: >- The minimum value for this tier. Billing will start counting from this value. Optional if no lower bound is needed. maxValue: type: number description: >- The maximum value for this tier. Optional if no upper bound is required. upTo: type: number description: >- 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. default: Infinity CreateContractAPIRequestModelcontractLimittiers: type: object required: - upTo properties: minValue: type: number description: >- The minimum value for this contract tier. Usage or billing calculations start from this threshold. maxValue: type: number description: >- The maximum value for this contract tier. Usage beyond this value will be restricted or handled according to contract rules. upTo: type: number description: >- Defines the upper bound for this tier. All usage up to this value will fall under this tier. Use Infinity for no upper limit. default: Infinity ContractData: properties: id: type: object customerId: type: object contractNumber: type: object contractTitle: type: object contractPeriod: type: object renewalPeriod: type: object noteContract: type: object billingFrequency: type: object usageBillingCycle: type: object estimateCycle: type: object billingTime: type: object startDate: type: object virtualStartDate: type: object endDate: type: object nextBillingDate: type: object billingDiscounts: type: object isPreusage: type: object billingReportLimit: type: object contractLimit: type: object creditTermId: type: object poNumber: type: object placeOfSupply: type: object billingAddress: type: object shippingAddress: type: object totalInvoicedAmount: type: object noteInvoice: type: object terms: type: object advanceConfig: type: object invoiceSplitConfig: type: object gstin: type: object companyGstin: type: object currency: type: object currencyId: type: object companyId: type: object createdBy: type: object updatedBy: type: object status: type: object autoRenew: type: object type: object ````