> ## Documentation Index > Fetch the complete documentation index at: https://docs.useaira.com/llms.txt > Use this file to discover all available pages before exploring further. # Create contract > Creates a new contract in draft status. Plan instances must be attached before the contract can be activated. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/contracts/ openapi: 3.1.0 info: title: API Reference version: '1.0' description: Aira API Reference x-logo: url: https://static.useaira.com/images/airalogo.svg backgroundColor: '#FFFFFF' altText: Aira Logo servers: - url: https://api.useaira.com description: API base URL security: - ApiKey: [] paths: /v1/contracts/: post: tags: - Contracts summary: Create contract description: >- Creates a new contract in draft status. Plan instances must be attached before the contract can be activated. requestBody: content: application/json: schema: type: object properties: customerId: type: string format: uuid description: ID of the customer associated with this contract. legalEntityId: type: string format: uuid nullable: true description: >- ID of the legal entity associated with this contract. Optional on create; defaults to the tenant's default legal entity when absent. startDate: type: string format: date description: Date when the contract becomes active. endDate: type: string format: date nullable: true description: >- Optional date when the contract expires. If null, the contract has no end date. retroactiveDate: type: string format: date nullable: true description: >- Optional retroactive date to apply contract changes from a past date. rateAdjustmentIndex: type: - 'null' - string enum: - none - igpm - ipca - other - null description: >- Reference index (e.g. IPCA) used to filter contracts when applying a mass adjustment on contracts. customFields: type: object description: >- Custom fields that can be associated with the entity. The fields must be previously created in the system before they can be used. additionalProperties: anyOf: - type: string - type: array items: type: string default: {} example: customField1: value1 customField2: - value2 - value3 taxRegimeId: type: string format: uuid nullable: true description: >- ID of the tax regime applied to invoices generated from this contract. Null when no regime is attached. invoiceAllocationStrategy: type: string enum: - single - percent_split - subsidiary_usage_split description: Invoice allocation strategy configured for the contract. includeNewSubsidiariesOnUsageScope: type: boolean description: >- Whether future subsidiaries are automatically included in usage scope. usageScopes: type: array items: type: object description: Usage scope customer configuration. properties: customerId: type: string format: uuid description: Customer ID that contributes usage to this contract. required: - customerId additionalProperties: false minItems: 1 description: Customers that compose the usage scope for this contract. uniqueItems: true allocations: type: array description: Payment account allocation configuration. items: type: object properties: paymentAccountId: type: string format: uuid description: ID of the payment account. allocationPercentage: type: string description: >- Allocation percentage in decimal format (0-100) with up to 6 decimal places. nullable: true required: - paymentAccountId - allocationPercentage additionalProperties: false minItems: 1 billingSettings: type: object description: Schema defining billing settings for a contract. properties: invoiceMinimumAmount: type: number description: The minimum amount for the entire contract invoice minimum: 0 productId: type: string format: uuid description: >- Product ID to use for contract minimum amount line items. required: - invoiceMinimumAmount - productId additionalProperties: false nullable: true billingSchedule: type: object description: Schema defining billing schedule for a contract. properties: periodUnit: type: string enum: - week - month - year description: >- The unit of time for the billing period (week, month, or year). anchorSource: type: string enum: - based_on_contract_start_date - explicit - first_day_of_month - first_day_of_week - first_day_of_year description: Source for determining billing anchor date. anchorDay: type: number minimum: 1 maximum: 31 description: >- Day of the period to anchor billing. For weekly: 1-7 (day of week), for monthly/yearly: 1-31 (day of month). anchorMonth: type: number minimum: 1 maximum: 12 nullable: true description: >- Month to anchor billing (required for annual billing, 1-12). required: - periodUnit - anchorSource - anchorDay - anchorMonth additionalProperties: false paymentGatewaySettings: type: object description: Schema defining payment gateway settings for a contract. properties: paymentMethod: type: string enum: - bolepix - bank_slip - pix - credit_card description: Payment method to use for this contract. default: bolepix dueOffsetDays: type: number minimum: 1 description: >- Number of days after the payment start date until payment is due (minimum of 1 day). required: - dueOffsetDays additionalProperties: false nullable: true required: - customerId - startDate - endDate - retroactiveDate - rateAdjustmentIndex - customFields - invoiceAllocationStrategy - includeNewSubsidiariesOnUsageScope - usageScopes - allocations - billingSchedule additionalProperties: false required: true description: Schema defining a contract. responses: '201': description: Schema defining a contract. content: application/json: schema: type: object properties: id: type: string format: uuid description: Unique identifier for the contract. customerId: type: string format: uuid description: ID of the customer associated with this contract. legalEntityId: type: string format: uuid nullable: true description: >- ID of the legal entity associated with this contract. Optional on create; defaults to the tenant's default legal entity when absent. legalEntity: type: object description: Legal entity summary embedded on contract responses. properties: id: type: string format: uuid description: >- The unique identifier of the legal entity in our system. businessName: type: string description: >- Registered business name (razão social) of the legal entity. tradeName: type: string nullable: true description: >- Trade name (nome fantasia) of the legal entity. Null when absent. required: - id - businessName - tradeName additionalProperties: false startDate: type: string format: date description: Date when the contract becomes active. endDate: type: string format: date nullable: true description: >- Optional date when the contract expires. If null, the contract has no end date. retroactiveDate: type: string format: date nullable: true description: >- Optional retroactive date to apply contract changes from a past date. status: type: string enum: - active - canceled - completed - draft description: Current status of the contract. rateAdjustmentIndex: type: - 'null' - string enum: - none - igpm - ipca - other - null description: >- Reference index (e.g. IPCA) used to filter contracts when applying a mass adjustment on contracts. customFields: type: object description: >- Custom fields that can be associated with the entity. The fields must be previously created in the system before they can be used. additionalProperties: anyOf: - type: string - type: array items: type: string default: {} example: customField1: value1 customField2: - value2 - value3 taxRegimeId: type: string format: uuid nullable: true description: >- ID of the tax regime applied to invoices generated from this contract. Null when no regime is attached. invoiceAllocationStrategy: type: string enum: - single - percent_split - subsidiary_usage_split description: Invoice allocation strategy configured for the contract. includeNewSubsidiariesOnUsageScope: type: boolean description: >- Whether future subsidiaries are automatically included in usage scope. usageScopes: type: array items: type: object description: Usage scope customer configuration. properties: customerId: type: string format: uuid description: Customer ID that contributes usage to this contract. required: - customerId additionalProperties: false minItems: 1 description: Customers that compose the usage scope for this contract. uniqueItems: true allocations: type: array description: Payment account allocation configuration. items: type: object properties: paymentAccountId: type: string format: uuid description: ID of the payment account. allocationPercentage: type: string description: >- Allocation percentage in decimal format (0-100) with up to 6 decimal places. nullable: true required: - paymentAccountId - allocationPercentage additionalProperties: false minItems: 1 billingSettings: type: object description: Schema defining billing settings for a contract. properties: invoiceMinimumAmount: type: number description: The minimum amount for the entire contract invoice minimum: 0 productId: type: string format: uuid description: >- Product ID to use for contract minimum amount line items. required: - invoiceMinimumAmount - productId additionalProperties: false nullable: true billingSchedule: type: object description: Schema defining billing schedule for a contract. properties: periodUnit: type: string enum: - week - month - year description: >- The unit of time for the billing period (week, month, or year). anchorSource: type: string enum: - based_on_contract_start_date - explicit - first_day_of_month - first_day_of_week - first_day_of_year description: Source for determining billing anchor date. anchorDay: type: number minimum: 1 maximum: 31 description: >- Day of the period to anchor billing. For weekly: 1-7 (day of week), for monthly/yearly: 1-31 (day of month). anchorMonth: type: number minimum: 1 maximum: 12 nullable: true description: >- Month to anchor billing (required for annual billing, 1-12). required: - periodUnit - anchorSource - anchorDay - anchorMonth additionalProperties: false paymentGatewaySettings: type: object description: Schema defining payment gateway settings for a contract. properties: paymentMethod: type: string enum: - bolepix - bank_slip - pix - credit_card description: Payment method to use for this contract. default: bolepix dueOffsetDays: type: number minimum: 1 description: >- Number of days after the payment start date until payment is due (minimum of 1 day). required: - dueOffsetDays additionalProperties: false nullable: true required: - id - customerId - startDate - endDate - retroactiveDate - status - rateAdjustmentIndex - customFields - invoiceAllocationStrategy - includeNewSubsidiariesOnUsageScope - usageScopes - allocations - billingSchedule additionalProperties: false '400': description: Error object returned to the client. content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error code: type: string description: A unique identifier for the type of error details: oneOf: - type: object additionalProperties: true - type: array description: >- Additional context about the error, such as invalid fields or constraints. Each endpoint may include specific error details in their documentation causations: type: array description: >- Optional array of error objects following the same structure as the parent error. Only present when there's a meaningful chain of related errors to expose items: type: object properties: message: type: string description: >- A human-readable description of the underlying error cause code: type: string description: A unique identifier for the type of underlying error details: type: object additionalProperties: true description: Additional context about the underlying error required: - message - code additionalProperties: false required: - code - message additionalProperties: false '404': description: Error object returned to the client when a resource is not found. content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error components: securitySchemes: ApiKey: type: apiKey description: API Key Authentication. name: X-API-KEY in: header ````