> ## 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 / Update an Invoice ## OpenAPI ````yaml POST /external/invoice/upsert 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: /external/invoice/upsert: post: tags: - external operationId: post_invoice_upsert_routes parameters: - name: X-Valyx-Signature in: header required: true description: Auth key for fetching ledger entries schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateInvoice' responses: '200': description: Success content: application/json: schema: type: object properties: {} components: schemas: CreateInvoice: properties: invoice: $ref: '#/components/schemas/CreateInvoiceModel' type: object CreateInvoiceModel: required: - invoiceAdjustedAmount - invoiceCurrency - invoiceId - invoiceNumber - invoicePaidAmount - invoiceSubtotal - invoiceTotal properties: invoiceId: type: string description: invoiceId invoiceNumber: type: string description: invoiceNumber invoiceDate: type: object invoiceDueDate: type: object promiseToPayDate: type: object invoiceSubtotal: type: number description: invoiceSubtotal invoiceTax: $ref: '#/components/schemas/CreateInvoiceModelinvoiceTax' invoiceAdjustedAmount: type: number description: invoiceAdjustedAmount default: 0 invoicePaidAmount: type: number description: invoicePaidAmount default: 0 discount: $ref: '#/components/schemas/CreateInvoiceModeldiscount' discounts: type: array items: $ref: '#/components/schemas/CreateInvoiceModeldiscounts' discountSplitByWeight: type: boolean description: discountSplitByWeight default: true invoiceTotal: type: number description: invoiceTotal default: 0 invoiceAcceptanceStatus: type: string example: PENDING enum: - PENDING - ACCEPTED - REJECTED customerId: type: string description: customerId customerDetails: $ref: '#/components/schemas/CreateInvoiceModelcustomerDetails' customerName: type: string description: customerName invoiceType: type: string description: invoiceType supplyStateCode: type: string description: supplyStateCode placeOfSupply: type: string description: placeOfSupply invoiceCurrency: type: string description: invoiceCurrency default: INR invoiceCurrencyId: type: string description: invoiceCurrencyId exchangeRate: type: number description: >- Exchange rate from invoice currency (FCY) to base currency (BCY). Formula - BCY amount = FCY amount × exchangeRate. Required when invoiceCurrency is not the company's base currency. If omitted, defaults to 1.0. example: 19.45 lineItems: type: array items: $ref: '#/components/schemas/CreateInvoiceModellineItems' referenceType: type: string description: referenceType referenceId: type: string description: referenceId referenceText: type: string description: referenceText eInvoiceQrCode: type: string description: eInvoiceQrCode irnNumber: type: string description: irnNumber companyId: type: string description: companyId tags: type: object metaData: type: object sort: type: string description: sort invoiceRoundingConfig: $ref: '#/components/schemas/CreateInvoiceModelinvoiceRoundingConfig' prepaidAmount: type: number description: prepaidAmount createInvoiceAdjustments: type: array items: $ref: '#/components/schemas/CreateInvoiceModelcreateInvoiceAdjustments' erpId: type: string description: erpId invoiceOriginSource: type: string enum: - ZOHO - IRECKONER - BOLTIC - VALYX - OTHER default: OTHER description: > Where this invoice originated. Stored on the invoice-extra row and returned on `GET /external/invoices` as `invoiceOriginSource`. Optional — defaults to `OTHER` when omitted. Set to `VALYX` when uploading invoices that were raised inside the Valyx platform (e.g. manual uploads of Valyx-generated invoices). example: VALYX type: object CreateInvoiceModelinvoiceTax: required: - total properties: total: type: number description: total default: 0 gstTax: $ref: '#/components/schemas/CreateInvoiceModelinvoiceTaxgstTax' cessTax: $ref: '#/components/schemas/CreateInvoiceModelinvoiceTaxcessTax' serviceTax: $ref: '#/components/schemas/CreateInvoiceModelinvoiceTaxserviceTax' tdsTax: $ref: '#/components/schemas/CreateInvoiceModelinvoiceTaxtdsTax' otherTaxes: type: array items: $ref: '#/components/schemas/CreateInvoiceModelinvoiceTaxotherTaxes' cgst: type: number description: cgst sgst: type: number description: sgst igst: type: number description: igst tds: type: number description: tds default: 0 type: object CreateInvoiceModeldiscount: required: - amount - isPostTax - percentage properties: amount: type: number description: amount default: 0 percentage: type: number description: percentage default: 0 isPostTax: type: boolean description: isPostTax default: false type: object CreateInvoiceModeldiscounts: required: - amount - isPostTax - percentage properties: amount: type: number description: amount default: 0 percentage: type: number description: percentage default: 0 isPostTax: type: boolean description: isPostTax default: false type: object CreateInvoiceModelcustomerDetails: required: - buyerId - isManuallyCreated properties: buyerId: type: string description: buyerId taxIdentifiers: type: array items: $ref: >- #/components/schemas/CreateInvoiceModelcustomerDetailstaxIdentifiers isManuallyCreated: type: boolean description: isManuallyCreated default: true companyId: type: string description: companyId name: type: string description: name alias: type: string description: alias registeredAddress: $ref: >- #/components/schemas/CreateInvoiceModelcustomerDetailsregisteredAddress addresses: type: array items: $ref: '#/components/schemas/CreateInvoiceModelcustomerDetailsaddresses' contactsData: type: array items: $ref: '#/components/schemas/CreateInvoiceModelcustomerDetailscontactsData' ownersData: type: array items: $ref: '#/components/schemas/CreateInvoiceModelcustomerDetailsownersData' stateCode: type: string description: stateCode countryCode: type: string description: countryCode default: IN country: type: string description: country primaryPhone: type: string description: primaryPhone primaryEmail: type: string description: primaryEmail customerContactPerson: type: string description: customerContactPerson currency: type: string description: currency default: INR currencyId: type: string description: currencyId tags: type: object metaData: type: object customerStatus: type: string example: PROSPECT enum: - PROSPECT - LIVE - CHURNED - INACTIVE upcomingCustomerStatus: type: string example: PROSPECT enum: - PROSPECT - LIVE - CHURNED - INACTIVE upcomingCustomerStatusChangeDate: type: string format: date description: upcomingCustomerStatusChangeDate upcomingCustomerStatusChangeReason: type: string description: upcomingCustomerStatusChangeReason upcomingCustomerStatusChangeByUserid: type: string description: upcomingCustomerStatusChangeByUserid erpId: type: string description: erpId type: object CreateInvoiceModellineItems: required: - subTotal - total properties: lineItemDetails: $ref: '#/components/schemas/CreateInvoiceModellineItemslineItemDetails' subTotal: type: number description: subTotal default: 0 total: type: number description: total default: 0 tax: $ref: '#/components/schemas/CreateInvoiceModellineItemstax' discount: $ref: '#/components/schemas/CreateInvoiceModellineItemsdiscount' quantity: type: number description: quantity default: 1 type: object CreateInvoiceModelinvoiceRoundingConfig: required: - isPostTax - roundingDirection - type properties: type: type: string example: NEAREST enum: - NEAREST - UP - DOWN roundingDirection: type: string example: UP enum: - UP - DOWN decimalPlace: type: integer description: decimalPlace default: 2 isPostTax: type: boolean description: isPostTax default: true type: object CreateInvoiceModelcreateInvoiceAdjustments: required: - isPostTax properties: isPostTax: type: boolean description: isPostTax default: true amount: type: number description: amount name: type: string description: name reference: type: string description: reference type: object CreateInvoiceModelinvoiceTaxgstTax: required: - cgst - cgstRate - igst - igstRate - sgst - sgstRate - totalGst - totalGstRate properties: totalGst: type: number description: totalGst default: 0 totalGstRate: type: number description: totalGstRate default: 0 cgst: type: number description: cgst default: 0 cgstRate: type: number description: cgstRate default: 0 sgst: type: number description: sgst default: 0 sgstRate: type: number description: sgstRate default: 0 igst: type: number description: igst default: 0 igstRate: type: number description: igstRate default: 0 type: object CreateInvoiceModelinvoiceTaxcessTax: required: - cess - cessRate properties: cess: type: number description: cess default: 0 cessRate: type: number description: cessRate default: 0 type: object CreateInvoiceModelinvoiceTaxserviceTax: required: - serviceTax - serviceTaxRate properties: serviceTax: type: number description: serviceTax default: 0 serviceTaxRate: type: number description: serviceTaxRate default: 0 type: object CreateInvoiceModelinvoiceTaxtdsTax: required: - tds - tdsRate properties: tds: type: number description: tds default: 0 tdsRate: type: number description: tdsRate default: 0 type: object CreateInvoiceModelinvoiceTaxotherTaxes: required: - genericTax - genericTaxRate - name properties: name: type: string description: name genericTax: type: number description: genericTax default: 0 genericTaxRate: type: number description: genericTaxRate default: 0 type: object CreateInvoiceModelcustomerDetailstaxIdentifiers: required: - value properties: value: type: string description: value type: type: string example: GSTIN enum: - GSTIN - PAN - VAT - OTHER type: object CreateInvoiceModelcustomerDetailsregisteredAddress: properties: line1: type: string description: line1 line2: type: string description: line2 state: type: string description: state city: type: string description: city country: type: string description: country zipCode: type: string description: zipCode type: object CreateInvoiceModelcustomerDetailsaddresses: properties: line1: type: string description: line1 line2: type: string description: line2 state: type: string description: state city: type: string description: city country: type: string description: country zipCode: type: string description: zipCode type: object CreateInvoiceModelcustomerDetailscontactsData: required: - id - name - primaryEmail - primaryPhone - role properties: id: type: string description: id name: type: string description: name primaryPhone: type: string description: primaryPhone primaryEmail: type: string description: primaryEmail role: type: string description: role type: object CreateInvoiceModelcustomerDetailsownersData: required: - id - name - primaryEmail - primaryPhone properties: id: type: string description: id name: type: string description: name primaryPhone: type: string description: primaryPhone primaryEmail: type: string description: primaryEmail role: type: string description: role isRegistered: type: boolean description: isRegistered default: false type: object CreateInvoiceModellineItemslineItemDetails: required: - name - pricePerItem - taxRate properties: name: type: string description: name taxRate: type: number description: taxRate pricePerItem: type: number description: pricePerItem default: 0 hsnOrSacCode: type: string description: hsnOrSacCode description: type: string description: description companyId: type: string description: companyId erpId: type: string description: erpId lineItemId: type: string description: lineItemId type: object CreateInvoiceModellineItemstax: required: - total properties: total: type: number description: total default: 0 gstTax: $ref: '#/components/schemas/CreateInvoiceModellineItemstaxgstTax' cessTax: $ref: '#/components/schemas/CreateInvoiceModellineItemstaxcessTax' serviceTax: $ref: '#/components/schemas/CreateInvoiceModellineItemstaxserviceTax' tdsTax: $ref: '#/components/schemas/CreateInvoiceModellineItemstaxtdsTax' otherTaxes: type: array items: $ref: '#/components/schemas/CreateInvoiceModellineItemstaxotherTaxes' cgst: type: number description: cgst sgst: type: number description: sgst igst: type: number description: igst tds: type: number description: tds default: 0 type: object CreateInvoiceModellineItemsdiscount: required: - amount - isPostTax - percentage properties: amount: type: number description: amount default: 0 percentage: type: number description: percentage default: 0 isPostTax: type: boolean description: isPostTax default: false type: object CreateInvoiceModellineItemstaxgstTax: required: - cgst - cgstRate - igst - igstRate - sgst - sgstRate - totalGst - totalGstRate properties: totalGst: type: number description: totalGst default: 0 totalGstRate: type: number description: totalGstRate default: 0 cgst: type: number description: cgst default: 0 cgstRate: type: number description: cgstRate default: 0 sgst: type: number description: sgst default: 0 sgstRate: type: number description: sgstRate default: 0 igst: type: number description: igst default: 0 igstRate: type: number description: igstRate default: 0 type: object CreateInvoiceModellineItemstaxcessTax: required: - cess - cessRate properties: cess: type: number description: cess default: 0 cessRate: type: number description: cessRate default: 0 type: object CreateInvoiceModellineItemstaxserviceTax: required: - serviceTax - serviceTaxRate properties: serviceTax: type: number description: serviceTax default: 0 serviceTaxRate: type: number description: serviceTaxRate default: 0 type: object CreateInvoiceModellineItemstaxtdsTax: required: - tds - tdsRate properties: tds: type: number description: tds default: 0 tdsRate: type: number description: tdsRate default: 0 type: object CreateInvoiceModellineItemstaxotherTaxes: required: - genericTax - genericTaxRate - name properties: name: type: string description: name genericTax: type: number description: genericTax default: 0 genericTaxRate: type: number description: genericTaxRate default: 0 type: object ````