> ## 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 invoice > Creates a one-off invoice in `open` status. Provide exactly one of `customerId` or `externalCustomerId`. When `paymentAccountId` is omitted or null, one of the customer's payment accounts is used. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/invoices/ 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/invoices/: post: tags: - Invoices summary: Create invoice description: >- Creates a one-off invoice in `open` status. Provide exactly one of `customerId` or `externalCustomerId`. When `paymentAccountId` is omitted or null, one of the customer's payment accounts is used. requestBody: content: application/json: schema: type: object properties: idempotencyKey: type: string minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ description: A unique idempotency key associated with the invoice. customerId: type: string format: uuid nullable: true description: >- The unique identifier of the customer in our system that this invoice will be associated with. externalCustomerId: type: string pattern: ^[a-zA-Z0-9_-]+$ nullable: true description: >- The external identifier of the customer that this invoice will be associated with. paymentAccountId: type: string format: uuid nullable: true description: >- The unique identifier of the payment account that will be used as the billing account. When omitted or null, one of the customer payment accounts is used. invoiceDate: type: string format: date description: >- The closing date of the invoice. It represents the end date of the period covered by the invoice. memo: type: string description: The memo to attach to the invoice. required: - idempotencyKey - invoiceDate - memo additionalProperties: false required: true description: >- Schema for creating a one-off invoice. Exactly one of customerId or externalCustomerId must be provided. When paymentAccountId is omitted or null, one of the customer payment accounts is used. responses: '200': description: Default Response content: application/json: schema: type: object properties: id: type: string format: uuid idempotencyKey: type: string customerId: type: string format: uuid paymentAccountId: type: string format: uuid contractId: type: string nullable: true format: uuid issuingAccount: type: object properties: tradeName: type: string nullable: true businessName: type: string emails: type: array items: type: string format: email taxId: type: string taxIdType: type: string enum: - cnpj - cpf zipCode: type: string nullable: true street: type: string nullable: true number: type: string nullable: true neighborhood: type: string nullable: true city: type: string nullable: true state: type: string enum: - AC - AL - AP - AM - BA - CE - DF - ES - GO - MA - MT - MS - MG - PA - PB - PR - PE - PI - RJ - RN - RS - RO - RR - SC - SP - SE - TO - null nullable: true country: type: string enum: - Brasil - null nullable: true complement: type: string nullable: true required: - tradeName - businessName - emails - taxId - taxIdType - zipCode - street - number - neighborhood - city - state - country - complement additionalProperties: false billingAccount: type: object properties: tradeName: type: string nullable: true businessName: type: string emails: type: array items: type: string format: email taxId: type: string taxIdType: type: string enum: - cnpj - cpf zipCode: type: string nullable: true street: type: string nullable: true number: type: string nullable: true neighborhood: type: string nullable: true city: type: string nullable: true state: type: string enum: - AC - AL - AP - AM - BA - CE - DF - ES - GO - MA - MT - MS - MG - PA - PB - PR - PE - PI - RJ - RN - RS - RO - RR - SC - SP - SE - TO - null nullable: true country: type: string enum: - Brasil - null nullable: true complement: type: string nullable: true required: - tradeName - businessName - emails - taxId - taxIdType - zipCode - street - number - neighborhood - city - state - country - complement additionalProperties: false invoiceAllocationStrategy: type: string enum: - single - percent_split lastCalculatedAt: type: string format: date-time nullable: true invoiceNumber: type: string invoiceDate: type: string format: date memo: type: string nullable: true subtotalAmount: type: number adjustmentAmount: type: number totalAmount: type: number discountAmount: type: number status: type: string enum: - open - in_review - issued - synced - pending - paid - overdue - canceled - failed isLocked: type: boolean failureReason: type: string enum: - erp_provider_not_supported - omie_settings_not_found - no_contract_found_in_omie_for_contract_number - contract_sync_not_found - contract_without_processor_id - senior_contract_without_processor_id - omie_mapping_basis_invalid - unexpected_error_on_invoice_sync - omie_service_mapping_not_found - omie_service_mappings_not_found_on_omie - omie_service_mapping_invalid - invoice_not_found - invoice_has_no_contract - unknown - payment_invoice_not_found - invoice_account_not_found - payment_account_not_found - insufficient_payment_amount - failed_to_upload_bank_slip - payment_unknown - null nullable: true source: type: string enum: - contract - one_off - import autoIssue: type: boolean amountDue: type: number nullable: true dueDate: type: string format: date nullable: true lineItemGroups: type: array items: type: object properties: id: type: string format: uuid idempotencyKey: type: string customerId: type: string format: uuid productId: type: string format: uuid planId: type: string nullable: true format: uuid planInstanceId: type: string nullable: true format: uuid name: type: string startDate: type: string format: date endDate: type: string format: date subtotalAmount: type: number adjustmentAmount: type: number totalAmount: type: number discountAmount: type: number lineItems: type: array items: type: object properties: id: type: string format: uuid idempotencyKey: type: string customerId: type: string format: uuid productId: type: string format: uuid itemId: type: string nullable: true format: uuid resourceId: type: string nullable: true format: uuid lineItemGroupId: type: string nullable: true format: uuid name: type: string scope: type: string enum: - credit_purchase - contract_minimum_amount - plan_minimum_amount - plan_fixed_amount - metric - additional_charge - one_off - tax_gross_up startDate: type: string format: date endDate: type: string format: date totalUsage: type: number nullable: true usageFormat: type: string enum: - unit - currency - null nullable: true subtotalAmount: type: number adjustmentAmount: type: number totalAmount: type: number discountAmount: type: number metadata: anyOf: - type: object properties: type: type: string enum: - metric billingModel: type: string enum: - in_full - proration priceTierDivision: type: string enum: - unique_tier - progressive required: - type - billingModel - priceTierDivision - type: object properties: type: type: string enum: - contract_minimum_amount minimumAmount: type: number minimumAmountApplied: type: number required: - type - minimumAmount - minimumAmountApplied - type: object properties: type: type: string enum: - plan_minimum_amount minimumAmount: type: number minimumAmountApplied: type: number required: - type - minimumAmount - minimumAmountApplied - type: 'null' subLineItems: type: array items: type: object properties: id: type: string format: uuid type: type: string enum: - fixed_price - minimum_amount - price_tier_flat - price_tier_unit - price_tier_package - price_tier_basis_points - proration - unit_price name: type: string description: type: string nullable: true usage: type: number nullable: true amount: type: number metadata: anyOf: - type: object properties: type: type: string enum: - fixed_price fixedPrice: type: number required: - type - fixedPrice - type: object properties: type: type: string enum: - minimum_amount minimumAmount: type: number minimumAmountApplied: type: number required: - type - minimumAmount - minimumAmountApplied - type: object properties: type: type: string enum: - price_tier_flat from: type: number to: type: number nullable: true fixedPrice: type: string required: - type - from - to - fixedPrice - type: object properties: type: type: string enum: - price_tier_unit from: type: number to: type: number nullable: true price: type: string fixedPrice: type: string nullable: true required: - type - from - to - price - fixedPrice - type: object properties: type: type: string enum: - price_tier_package from: type: number to: type: number nullable: true packageSize: type: number price: type: string fixedPrice: type: string nullable: true required: - type - from - to - packageSize - price - fixedPrice - type: object properties: type: type: string enum: - price_tier_basis_points from: type: number to: type: number nullable: true basisPoints: type: number fixedPrice: type: string nullable: true required: - type - from - to - basisPoints - fixedPrice - type: object properties: type: type: string enum: - proration intervalSize: type: number amount: type: string usage: type: number intervalStart: type: string format: date intervalEnd: type: string format: date required: - type - intervalSize - amount - usage - intervalStart - intervalEnd - type: object properties: type: type: string enum: - unit_price price: type: string required: - type - price required: - id - type - name - description - usage - amount - metadata additionalProperties: false adjustments: type: array items: type: object properties: id: type: string format: uuid name: type: string type: type: string enum: - monetary_discount - allocation_offset amount: type: number required: - id - name - type - amount additionalProperties: false required: - id - idempotencyKey - customerId - productId - resourceId - lineItemGroupId - name - scope - startDate - endDate - totalUsage - usageFormat - subtotalAmount - adjustmentAmount - totalAmount - discountAmount - metadata - subLineItems - adjustments additionalProperties: false required: - id - idempotencyKey - customerId - productId - planId - planInstanceId - name - startDate - endDate - subtotalAmount - adjustmentAmount - totalAmount - discountAmount - lineItems additionalProperties: false standaloneLineItems: type: array items: type: object properties: id: type: string format: uuid idempotencyKey: type: string customerId: type: string format: uuid productId: type: string format: uuid itemId: type: string nullable: true format: uuid resourceId: type: string nullable: true format: uuid lineItemGroupId: type: string nullable: true format: uuid name: type: string scope: type: string enum: - credit_purchase - contract_minimum_amount - plan_minimum_amount - plan_fixed_amount - metric - additional_charge - one_off - tax_gross_up startDate: type: string format: date endDate: type: string format: date totalUsage: type: number nullable: true usageFormat: type: string enum: - unit - currency - null nullable: true subtotalAmount: type: number adjustmentAmount: type: number totalAmount: type: number discountAmount: type: number metadata: anyOf: - type: object properties: type: type: string enum: - metric billingModel: type: string enum: - in_full - proration priceTierDivision: type: string enum: - unique_tier - progressive required: - type - billingModel - priceTierDivision - type: object properties: type: type: string enum: - contract_minimum_amount minimumAmount: type: number minimumAmountApplied: type: number required: - type - minimumAmount - minimumAmountApplied - type: object properties: type: type: string enum: - plan_minimum_amount minimumAmount: type: number minimumAmountApplied: type: number required: - type - minimumAmount - minimumAmountApplied - type: 'null' subLineItems: type: array items: type: object properties: id: type: string format: uuid type: type: string enum: - fixed_price - minimum_amount - price_tier_flat - price_tier_unit - price_tier_package - price_tier_basis_points - proration - unit_price name: type: string description: type: string nullable: true usage: type: number nullable: true amount: type: number metadata: anyOf: - type: object properties: type: type: string enum: - fixed_price fixedPrice: type: number required: - type - fixedPrice - type: object properties: type: type: string enum: - minimum_amount minimumAmount: type: number minimumAmountApplied: type: number required: - type - minimumAmount - minimumAmountApplied - type: object properties: type: type: string enum: - price_tier_flat from: type: number to: type: number nullable: true fixedPrice: type: string required: - type - from - to - fixedPrice - type: object properties: type: type: string enum: - price_tier_unit from: type: number to: type: number nullable: true price: type: string fixedPrice: type: string nullable: true required: - type - from - to - price - fixedPrice - type: object properties: type: type: string enum: - price_tier_package from: type: number to: type: number nullable: true packageSize: type: number price: type: string fixedPrice: type: string nullable: true required: - type - from - to - packageSize - price - fixedPrice - type: object properties: type: type: string enum: - price_tier_basis_points from: type: number to: type: number nullable: true basisPoints: type: number fixedPrice: type: string nullable: true required: - type - from - to - basisPoints - fixedPrice - type: object properties: type: type: string enum: - proration intervalSize: type: number amount: type: string usage: type: number intervalStart: type: string format: date intervalEnd: type: string format: date required: - type - intervalSize - amount - usage - intervalStart - intervalEnd - type: object properties: type: type: string enum: - unit_price price: type: string required: - type - price required: - id - type - name - description - usage - amount - metadata additionalProperties: false adjustments: type: array items: type: object properties: id: type: string format: uuid name: type: string type: type: string enum: - monetary_discount - allocation_offset amount: type: number required: - id - name - type - amount additionalProperties: false required: - id - idempotencyKey - customerId - productId - resourceId - lineItemGroupId - name - scope - startDate - endDate - totalUsage - usageFormat - subtotalAmount - adjustmentAmount - totalAmount - discountAmount - metadata - subLineItems - adjustments additionalProperties: false required: - id - idempotencyKey - customerId - paymentAccountId - contractId - issuingAccount - billingAccount - invoiceAllocationStrategy - lastCalculatedAt - invoiceNumber - invoiceDate - memo - subtotalAmount - adjustmentAmount - totalAmount - discountAmount - status - isLocked - failureReason - source - autoIssue - amountDue - dueDate - lineItemGroups - standaloneLineItems 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 '409': 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 components: securitySchemes: ApiKey: type: apiKey description: API Key Authentication. name: X-API-KEY in: header ````