> ## Documentation Index > Fetch the complete documentation index at: https://spidocs.chargebee.com/llms.txt > Use this file to discover all available pages before exploring further. # Submit a document > Submits a new document, such as an invoice or credit note, to the connected e-invoicing provider for validation, compliance checks, and delivery to the appropriate tax authorities or business partners. This endpoint is MANDATORY for enabling document submission through the Chargebee E-invoicing SPI framework. Within Chargebee, this endpoint is invoked asynchronously by an internal background job whenever a new invoice, credit note, or other supported billing document is generated and requires processing through the configured e-invoicing provider. If the e-invoicing provider requires merchants to configure field mappings manually, instead of relying on predefined mappings managed by Chargebee, Chargebee will collect this mapping as entered by the Chargebee merchant through the Chargebee Admin Console. The collected field mapping and the corresponding input values will be passed to the adapter via the `overrides` parameter. Note: When the `overrides` parameter is present, the adapter must rely exclusively on the `field_mapping` and `values` defined within it. All other standard schema fields should be ignored for transformation purposes. Additionally, this endpoint supports submission of Application Response documents, such as invoice acknowledgements or rejections, to facilitate downstream workflows and business rule validation. These responses are submitted using the same endpoint but distinguished using a type discriminator with APPLICATION_RESPONSE. ## OpenAPI ````yaml post /einvoicing/documents openapi: 3.0.0 info: description: > ## E-invoicing Service Provider Interface (SPI) - Overview Chargebee streamlines e-invoicing compliance across regions by facilitating the following operations throughout the billing lifecycle. 1) Retrieve E-invoicing Activations: - Retrieves the list of country and network activations that are configured in the connected e-invoicing provider platform. - Each activation reflects a country and e-invoicing network that has been set up and made available by the provider. - Chargebee uses this operation during provider enablement to determine which activations can be offered to merchants. 2) Document Submission: - Submits invoices and credit notes to external e-invoicing systems for validation, compliance processing, and delivery to tax authorities or trading partners. 3) Status Tracking: - Supports asynchronous document lifecycle tracking through webhook notifications sent by the e-invoicing adapter. These updates reflect real-time status changes as documents move through validation, compliance, and regulatory delivery stages. - Allows on-demand status checks to retrieve the latest processing state of submitted documents, ensuring continued visibility even if webhook delivery is delayed or disrupted. 4) Final Document Retrieval: - Retrieves finalized and regulator-approved documents for archiving, auditing or customer-facing use. Chargebee leverages external e-invoicing services to execute these operations effectively. These external e-invoicing servies are the certified vendors offering APIs to handle e-invoicing compliance and document exchange with tax authorities. ## The Role of the E-invoicing Adapter App: To connect with external e-invoicing systems, Chargebee uses an E-invoicing Adapter App - a bridge that enables secure and standardized communication between Chargebee and the e-invoicing system. This communication is governed by the E-invoicing Service Provider Interface (SPI). ## Building an E-invoicing Adapter App To integrate an e-invoicing system with Chargebee, you must implement the E-invoicing SPI by developing an adapter app. This is required in the following scenarios: - As an E-invoicing Provider: - Connect your compliance platform to Chargebee so merchants can automatically submit billing documents in a regulator-approved format. - As a System Integrator: - Build a connector that bridges a third-party e-invoicing provider and Chargebee, enabling seamless integration for merchants. By implementing the E-invoicing SPI, you enable Chargebee to support global regulatory compliance through a scalable and region-agnostic architecture. title: E-Invoicing Service Provider Interface version: 1.0.0 servers: - description: Production server (replace with actual service URL) url: https://api.example.com - description: Sandbox server for testing url: https://sandbox.example.com security: - ApiKeyAuth: [] tags: - description: Operations related to e-invoicing activations name: Activations - description: Operations related to e-invoicing documents name: Documents paths: /einvoicing/documents: post: tags: - Documents summary: Submit a document description: > Submits a new document, such as an invoice or credit note, to the connected e-invoicing provider for validation, compliance checks, and delivery to the appropriate tax authorities or business partners. This endpoint is MANDATORY for enabling document submission through the Chargebee E-invoicing SPI framework. Within Chargebee, this endpoint is invoked asynchronously by an internal background job whenever a new invoice, credit note, or other supported billing document is generated and requires processing through the configured e-invoicing provider. If the e-invoicing provider requires merchants to configure field mappings manually, instead of relying on predefined mappings managed by Chargebee, Chargebee will collect this mapping as entered by the Chargebee merchant through the Chargebee Admin Console. The collected field mapping and the corresponding input values will be passed to the adapter via the `overrides` parameter. Note: When the `overrides` parameter is present, the adapter must rely exclusively on the `field_mapping` and `values` defined within it. All other standard schema fields should be ignored for transformation purposes. Additionally, this endpoint supports submission of Application Response documents, such as invoice acknowledgements or rejections, to facilitate downstream workflows and business rule validation. These responses are submitted using the same endpoint but distinguished using a type discriminator with APPLICATION_RESPONSE. operationId: einvoicingDocumentSubmission requestBody: content: application/json: schema: $ref: '#/components/schemas/document' required: true responses: '200': content: application/json: examples: einvoice_document_submission_pending: description: >- A sample response indicating the document is under processing at the provider. summary: Document under processing value: document_id: DOC-20250402-0002 status: ACCEPTED request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 schema: $ref: '#/components/schemas/document_submission_response' description: Document submitted successfully. '400': content: application/json: examples: einvoice_document_submission_failed: description: >- A sample response when the request is invalid or missing required data. summary: Bad request value: errors: - code: MISSING_REQUIRED_DATA message: >- The request did not contain a required property 'taxAmount' help_url: >- https://docs.example.com/errors#MISSING_REQUIRED_PARAMETER schema: $ref: '#/components/schemas/bad_request_error_response' description: Bad request '401': description: Unauthorized '403': description: Forbidden '500': content: application/json: examples: unexpected_error: summary: Server error value: message: >- An unexpected error occurred while processing your request. schema: $ref: '#/components/schemas/500_error_response' description: Unexpected error while processing request. x-codeSamples: - lang: cURL label: Invoice document submission source: | curl --request POST \ --url https://partner.app.com/einvoicing/documents \ --header 'Content-Type: application/json' \ --header 'Authorization: {"api_key" : ... }' \ --data '{ "id": "INV-10001", "type": "INVOICE", "issue_date": "2025-04-02", "tax_date": "2025-04-02", "currency_code": "EUR", "due_date": "2025-04-30", "amount": 114.0, "note": "Payment due in 28 days.", "accounting_supplier_party": { "name": "Example Seller GmbH", "address": { "line_1": "Hauptstr. 456", "line_2": "Suite 5", "zip": "50667", "city": "Cologne", "country": "DE" }, "tax_scheme": [ { "scheme": "VAT", "id": "DE987654321" } ] }, "accounting_customer_party": { "name": "Example Buyer GmbH", "address": { "line_1": "Berliner Str. 123", "line_2": "2nd Floor", "zip": "10115", "city": "Berlin", "country": "DE" }, "tax_scheme": [ { "scheme": "VAT", "id": "DE123456789" } ] }, "payment_means": [ { "code": "ONLINE_PAYMENT_SERVICE", "payment_id": "PAY-2024-00987", "card_account": { "primary_account_number_id": "4111********1111", "card_holder_name": "Jane Smith", "network_id": "MASTERCARD" } } ], "lines": [ { "id": "1", "description": "Consulting Services - April", "quantity": 1, "unit_price": 100.0, "amount": 100.0, "item_code": "CONS-APRIL", "classified_tax_category": [ { "percentage": 14, "category": "VAT", "country": "DE" } ] } ], "tax_total": { "tax_amount": 14.0, "tax_sub_totals": [ { "taxable_amount": 100.0, "tax_amount": 14.0, "percentage": 14, "country": "DE", "category": "VAT" } ] } }' - lang: cURL label: Invoice document submission with overrides source: | curl --request POST \ --url https://partner.app.com/einvoicing/documents \ --header 'Content-Type: application/json' \ --header 'Authorization: {"api_key" : ... }' \ --data '{ "id": "INV-20221607", "type": "INVOICE", "issue_date": "2025-04-02", "tax_date": "2025-04-02", "currency_code": "EUR", "due_date": "2025-04-30", "amount": 114.0, "note": "Payment due in 28 days.", "accounting_supplier_party": { "name": "Example Seller GmbH", "address": { "line_1": "Hauptstr. 456", "line_2": "Suite 5", "zip": "50667", "city": "Cologne", "country": "DE" }, "tax_scheme": [ { "scheme": "VAT", "id": "DE987654321" } ] }, "accounting_customer_party": { "name": "Example Buyer GmbH", "address": { "line_1": "Berliner Str. 123", "line_2": "2nd Floor", "zip": "10115", "city": "Berlin", "country": "DE" }, "tax_scheme": [ { "scheme": "VAT", "id": "DE123456789" } ] }, "payment_means": [ { "code": "ONLINE_PAYMENT_SERVICE", "payment_id": "PAY-2024-00987", "card_account": { "primary_account_number_id": "4111********1111", "card_holder_name": "Jane Smith", "network_id": "MASTERCARD" } } ], "lines": [ { "id": "1", "description": "Consulting Services - April", "quantity": 1, "unit_price": 100.0, "amount": 100.0, "item_code": "CONS-APRIL", "classified_tax_category": [ { "percentage": 14, "category": "VAT", "country": "DE" } ] } ], "tax_total": { "tax_amount": 14.0, "tax_sub_totals": [ { "taxable_amount": 100.0, "tax_amount": 14.0, "percentage": 14, "country": "DE", "category": "VAT" } ] }, "overrides": { "country": "DE", "transaction_type": "B2B", "model": "PEPPOL", "document_type": "ubl-invoice", "field_mapping": [ { "target": "Invoice.cbc:ID", "source": "invoice.id" }, { "target": "Invoice.cbc:IssueDate", "source": "invoice.issue_date" }, { "target": "Invoice.cbc:InvoiceTypeCode", "fixed_value": "380" }, { "target": "Invoice.cbc:DocumentCurrencyCode", "source": "invoice.currency_code" }, { "target": "Invoice.cac:AccountingSupplierParty.cac:Party.cac:PostalAddress.cac:Country.cbc:IdentificationCode", "source": "business.address.country" }, { "target": "Invoice.cac:AccountingCustomerParty.cac:Party.cac:PostalAddress.cac:Country.cbc:IdentificationCode", "source": "customer.billing_address.country" }, { "target": "Invoice.cac:AccountingCustomerParty.cac:Party.cac:PartyIdentification.cbc:ID.@schemeID\"", "source": "customer.cf_einvoice_scheme_id" }, { "target": "Invoice.cac:TaxTotal.cbc:TaxAmount", "source": "invoice.tax_total" }, { "target": "Invoice.cbc:Note", "source": "invoice.note" }, { "target": "Invoice.cac:InvoiceLine.cbc:ID", "source": "line_items[].id" }, { "target": "Invoice.cac:InvoiceLine.cbc:InvoicedQuantity", "source": "line_items[].quantity" }, { "target": "Invoice.cac:InvoiceLine.cbc:InvoicedQuantity.@unitCode", "source": "line_items[].unit_code" }, { "target": "Invoice.cac:InvoiceLine.cbc:LineExtensionAmount", "source": "line_items[].amount" }, { "target": "Invoice.cac:InvoiceLine.cbc:LineExtensionAmount.@currencyID", "source": "invoice.currency_code" }, { "target": "Invoice.cac:InvoiceLine.cac:Item.cbc:Name", "source": "line_items[].description" }, { "target": "Invoice.cac:InvoiceLine.cac:Item.cac:ClassifiedTaxCategory.cbc:ID", "expr": "li.tax_rate > 0.0 && (!has(li.tax_exempt_reason) || li.tax_exempt_reason == '') ? 'S' :li.tax_rate == 0.0 && li.tax_exempt_reason == 'ZERO_RATED' ? 'Z' :li.tax_rate == 0.0 && li.tax_exempt_reason == 'EXEMPT' ? 'E' :li.tax_rate == 0.0 && li.tax_exempt_reason == 'REVERSE_CHARGE' ? 'AE' :li.tax_rate == 0.0 && li.tax_exempt_reason == 'OUTSIDE_SCOPE' ? 'O' :\n''" }, { "target": "Invoice.cac:InvoiceLine.cac:Item.cac:ClassifiedTaxCategory.cac:TaxScheme.cbc:ID", "source": "line_items[].classified_tax_category[].category" }, { "target": "Invoice.cac:InvoiceLine.cac:Price.cbc:PriceAmount", "source": "line_items[].unit_price" }, { "target": "Invoice.cac:InvoiceLine.cac:Price.cbc:PriceAmount.@currencyID", "source": "invoice.currency_code" }, { "target": "Invoice.cbc:Note", "source": "invoice.note" } ], "values": { "invoice.id": "INV-10001", "invoice.issue_date": "2025-04-02", "invoice.tax_date": "2025-04-02", "invoice.currency_code": "EUR", "invoice.due_date": "2025-04-30", "invoice.amount": 114.0, "invoice.note": "Payment due in 28 days.", "business.address.country": "DE", "customer.billing_address.country": "DE", "invoice.tax_total": 14.0, "line_items": [ { "id": "1", "description": "Consulting Services - April", "quantity": 1, "unit_price": 100.0, "amount": 100.0, "item_code": "CONS-APRIL", "tax_rate" : "14", "classified_tax_category": { "percentage": 14, "category": "VAT", "country": "DE" } }, { "id": "2", "description": "TEST Consulting Services - April", "quantity": 130, "unit_price": 1000.0, "amount": 1005.0, "item_code": "CONS-APRIL", "tax_rate" : "30", "classified_tax_category": { "percentage": 30, "category": "EU VAT", "country": "DE" } } ] } } }' - lang: cURL label: Credit note document submission source: | curl --request POST \ --url https://partner.app.com/einvoicing/documents \ --header 'Content-Type: application/json' \ --header 'Authorization: {"api_key" : ... }' \ --data '{ "id": "CN-20002", "type": "CREDIT_NOTE", "issue_date": "2025-04-10", "tax_date": "2025-04-10", "currency_code": "EUR", "due_date": "2025-04-30", "amount": 50.0, "note": "Credit issued for April billing adjustment.", "billing_reference": [ "INV-10001" ], "accounting_supplier_party": { "name": "Example Seller GmbH", "address": { "line_1": "Hauptstr. 456", "line_2": "Suite 5", "zip": "50667", "city": "Cologne", "country": "DE" }, "tax_scheme": [ { "scheme": "VAT", "id": "DE987654321" } ] }, "accounting_customer_party": { "name": "Example Buyer GmbH", "address": { "line_1": "Berliner Str. 123", "line_2": "2nd Floor", "zip": "10115", "city": "Berlin", "country": "DE" }, "tax_scheme": [ { "scheme": "VAT", "id": "DE123456789" } ] }, "payment_means": [ { "code": "ONLINE_PAYMENT_SERVICE", "payment_id": "PAY-2024-01002", "card_account": { "primary_account_number_id": "4111********2222", "card_holder_name": "John Doe", "network_id": "VISA" } } ], "lines": [ { "id": "1", "description": "Refund for overcharge in April", "quantity": 1, "unit_price": 50.0, "amount": 50.0, "item_code": "APRIL-REFUND", "classified_tax_category": [ { "percentage": 14, "category": "VAT", "country": "DE" } ] } ], "tax_total": { "tax_amount": 7.0, "tax_sub_totals": [ { "taxable_amount": 50.0, "tax_amount": 7.0, "percentage": 14, "country": "DE", "category": "VAT" } ] } }' - lang: cURL label: Credit note document submission with overrides source: | curl --request POST \ --url https://partner.app.com/einvoicing/documents \ --header 'Content-Type: application/json' \ --header 'Authorization: {"api_key" : ... }' \ --data '{ "id": "CN-20002", "type": "CREDIT_NOTE", "issue_date": "2025-04-10", "tax_date": "2025-04-10", "currency_code": "EUR", "due_date": "2025-04-30", "amount": 50.0, "note": "Credit issued for April billing adjustment.", "billing_reference": [ "INV-10001" ], "accounting_supplier_party": { "name": "Example Seller GmbH", "address": { "line_1": "Hauptstr. 456", "line_2": "Suite 5", "zip": "50667", "city": "Cologne", "country": "DE" }, "tax_scheme": [ { "scheme": "VAT", "id": "DE987654321" } ] }, "accounting_customer_party": { "name": "Example Buyer GmbH", "address": { "line_1": "Berliner Str. 123", "line_2": "2nd Floor", "zip": "10115", "city": "Berlin", "country": "DE" }, "tax_scheme": [ { "scheme": "VAT", "id": "DE123456789" } ] }, "payment_means": [ { "code": "ONLINE_PAYMENT_SERVICE", "payment_id": "PAY-2024-01002", "card_account": { "primary_account_number_id": "4111********2222", "card_holder_name": "John Doe", "network_id": "VISA" } } ], "lines": [ { "id": "1", "description": "Refund for overcharge in April", "quantity": 1, "unit_price": 50.0, "amount": 50.0, "item_code": "APRIL-REFUND", "classified_tax_category": [ { "percentage": 14, "category": "VAT", "country": "DE" } ] } ], "tax_total": { "tax_amount": 7.0, "tax_sub_totals": [ { "taxable_amount": 50.0, "tax_amount": 7.0, "percentage": 14, "country": "DE", "category": "VAT" } ] }, "overrides": { "country": "DE", "transaction_type": "B2B", "model": "PEPPOL", "document_type": "ubl-creditnote", "field_mapping": [ { "target": "Creditnote.cbc:ID", "source": "credit_note.id" }, { "target": "Creditnote.cbc:IssueDate", "source": "credit_note.issue_date" }, { "target": "Creditnote.cbc:CreditNoteTypeCode", "fixed_value": "396" }, { "target": "Creditnote.cbc:DocumentCurrencyCode", "source": "credit_note.currency_code" }, { "target": "Creditnote.cac:BillingReference", "expr": "invoiceResponse.events.exists(e, has(e.responseKey) && e.responseKey == 'Receipt Message ID') ? invoiceResponse.events.filter(e, has(e.responseKey) && e.responseKey == 'Receipt Message ID').map(e, e.responseValue)[0] : null" }, { "target": "Creditnote.cac:AccountingSupplierParty.cac:Party.cbc:EndpointID", "source": "business.legal_entity.company_id" }, { "target": "Creditnote.cac:AccountingSupplierParty.cac:Party.cac:PostalAddress.cac:Country.cbc:IdentificationCode", "source": "business.address.country" }, { "target": "Creditnote.cac:AccountingSupplierParty.cac:Party.cac:PartyLegalEntity.cbc:RegistrationName", "source": "business.legal_entity.registration_name" }, { "target": "Creditnote.cac:AccountingCustomerParty.cac:Party.cbc:EndpointID", "source": "customer.legal_entity.company_id" }, { "target": "Creditnote.cac:AccountingCustomerParty.cac:Party.cac:PostalAddress.cac:Country.cbc:IdentificationCode", "source": "customer.billing_address.country" }, { "target": "Creditnote.cac:AccountingCustomerParty.cac:Party.cac:PartyLegalEntity.cbc:RegistrationName", "source": "customer.legal_entity.registration_name" }, { "target": "Invoice.cac:AccountingCustomerParty.cac:Party.cac:PartyIdentification.cbc:ID.@schemeID\"", "source": "customer.cf_einvoice_scheme_id" }, { "target": "Creditnote.cac:TaxTotal.cbc:TaxAmount", "source": "credit_note.tax_total" }, { "target": "Creditnote.cac:TaxTotal.cbc:TaxAmount.@currencyID", "source": "credit_note.currency_code" }, { "target": "Creditnote.cac:InvoiceLine.cbc:ID", "source": "line_items[].id" }, { "target": "Creditnote.cac:InvoiceLine.cbc:InvoicedQuantity", "source": "line_items[].quantity" }, { "target": "Creditnote.cac:InvoiceLine.cbc:InvoicedQuantity.@unitCode", "source": "line_items[].unit_code" }, { "target": "Creditnote.cac:InvoiceLine.cbc:LineExtensionAmount", "source": "line_items[].amount" }, { "target": "Creditnote.cac:InvoiceLine.cbc:LineExtensionAmount.@currencyID", "source": "credit_note.currency_code" }, { "target": "Creditnote.cac:InvoiceLine.cac:Item.cbc:Name", "source": "line_items[].description" }, { "target": "Creditnote.cac:InvoiceLine.cac:Item.cac:ClassifiedTaxCategory.cbc:ID", "source": "line_items[].classified_tax_category[].category" }, { "target": "Creditnote.cac:InvoiceLine.cac:Item.cac:ClassifiedTaxCategory.cac:TaxScheme.cbc:ID", "source": "line_items[].classified_tax_category[].category" }, { "target": "Creditnote.cac:InvoiceLine.cac:Price.cbc:PriceAmount", "source": "line_items[].unit_price" }, { "target": "Creditnote.cac:InvoiceLine.cac:Price.cbc:PriceAmount.@currencyID", "source": "credit_note.currency_code" }, { "target": "Creditnote.cbc:Note", "expr: "credit_note.amount > 0 ? 'Partial refund issued' : credit_note.custom_fields.cf_credit_note_reason != null ? credit_note.custom_fields.cf_credit_note_reason : 'Credit note issued'" } ], "values": { "credit_note.id": "CN-20001", "credit_note.issue_date": "2025-04-05", "credit_note.tax_date": "2025-04-05", "credit_note.currency_code": "EUR", "credit_note.due_date": "2025-04-30", "credit_note.amount": 140.0, "credit_note.billing_reference": { "invoice_document_reference": { "id": "INV-10001", "issue_date": "2025-04-02" } }, "credit_note.note": "Refund for April invoice", "business.address.country": "DE", "business.legal_entity.company_id": "987654321", "business.legal_entity.registration_name": "Example Seller GmbH", "customer.billing_address.country": "DE", "customer.legal_entity.company_id": "123456789", "customer.legal_entity.registration_name": "Example Buyer GmbH", "credit_note.tax_total": 40.0, "invoiceResponse": { "events": [ { "responseKey": "Some Other Event", "responseValue": "Some Value" }, { "responseKey": "Receipt Message ID", "responseValue": "RCPT123456" }, { "responseKey": "Another Event", "responseValue": "Another Value" } ] }, "line_items": [ { "id": "1", "description": "Reversal of April service", "quantity": 1, "unit_price": 100.0, "amount": 100.0, "unit_code": "EA", "classified_tax_category": { "percentage": 14, "category": "VAT", "country": "DE" } }, { "id": "2", "description": "Reversal of consulting charge", "quantity": 1, "unit_price": 40.0, "amount": 40.0, "unit_code": "EA", "classified_tax_category": { "percentage": 30, "category": "EU VAT", "country": "DE" } } ] } } }' - lang: cURL label: Application response document submission source: | curl --request POST \ --url https://partner.app.com/einvoicing/documents \ --header 'Content-Type: application/json' \ --header 'Authorization: {"api_key" : ... }' \ --data '{ "id": "APPRESP-20250402-002", "type": "APPLICATION_RESPONSE", "issue_date": "2025-04-04", "sender_party": { "legal_entity": { "registration_name": "Example Sender GmbH", "company_id": "DE998877665" } }, "receiver_party": { "legal_entity": { "registration_name": "Example Receiver GmbH", "company_id": "DE112233445" } }, "document_response": { "response": { "status": "Under query", "note": "Discrepancy in line item total" }, "document_reference": { "id": "INV-20250401-789" } } }' - lang: cURL label: Application response document submission with overrides source: | curl --request POST \ --url https://partner.app.com/einvoicing/documents \ --header 'Content-Type: application/json' \ --header 'Authorization: {"api_key" : ... }' \ --data '{ "id": "APPRESP-20240401-001", "type": "APPLICATION_RESPONSE", "issue_date": "2025-04-03", "sender_party": { "legal_entity": { "registration_name": "Example Sender GmbH", "company_id": "DE123456789" } }, "receiver_party": { "legal_entity": { "registration_name": "Example Receiver GmbH", "company_id": "DE987654321" } }, "document_response": { "response": { "status": "Accepted", "note": "Invoice accepted without issues" }, "document_reference": { "id": "INV-20240330-567" } }, "overrides": { "country": "DE", "model": "PEPPOL", "transaction_type": "B2B", "document_type": "ubl-applicationresponse", "field_mapping": [ { "target": "ApplicationResponse.cbc:ID", "source": "application_response.id" }, { "target": "ApplicationResponse.cbc:IssueDate", "source": "application_response.issue_date" }, { "target": "ApplicationResponse.cac:SenderParty.cac:PartyLegalEntity.cbc:RegistrationName", "source": "application_response.sender_party.legal_entity.registration_name" }, { "target": "ApplicationResponse.cac:ReceiverParty.cac:PartyLegalEntity.cbc:RegistrationName", "source": "application_response.receiver_party.legal_entity.registration_name" }, { "target": "ApplicationResponse.cac:DocumentResponse.cac:Response.cbc:ResponseCode", "source": "application_response.document_response.response.status" }, { "target": "ApplicationResponse.cac:DocumentResponse.cac:Response.cbc:Description", "source": "application_response.document_response.response.note" }, { "target": "ApplicationResponse.cac:DocumentResponse.cac:DocumentReference.cbc:ID", "source": "application_response.document_response.document_reference.id" } ], "values": { "application_response.id": "APPRESP-20240401-001", "application_response.issue_date": "2025-04-03", "application_response.sender_party.legal_entity.registration_name": "Example Sender GmbH", "application_response.receiver_party.legal_entity.registration_name": "Example Receiver GmbH", "application_response.document_response.response.status": "Accepted", "application_response.document_response.response.note": "Invoice accepted without issues", "application_response.document_response.document_reference.id": "INV-20240330-567" } } }' components: schemas: document: discriminator: mapping: INVOICE: $ref: '#/components/schemas/main_document' CREDIT_NOTE: $ref: '#/components/schemas/main_document' APPLICATION_RESPONSE: $ref: '#/components/schemas/application_response_document' propertyName: type oneOf: - $ref: '#/components/schemas/main_document' - $ref: '#/components/schemas/application_response_document' type: object document_submission_response: example: provider_interaction: request: body: '{}' response: status_code: 0 body: '{}' document_id: document_id request_id: request_id status: ACCEPTED properties: document_id: description: >- The unique identifier assigned to the document by the e-invoicing provider. This identifier must be used for subsequent operations such as retrieving the document status and downloading the document. type: string status: description: The current status of the submitted document. enum: - ACCEPTED - FAILED - SUCCESS type: string request_id: description: >- A unique identifier assigned to the request for tracking and correlation purposes across systems and logs. type: string provider_interaction: $ref: >- #/components/schemas/document_submission_response_provider_interaction required: - document_id - status type: object bad_request_error_response: example: errors: - code: MISSING_REQUIRED_DATA message: The request did not contain a required property 'taxAmount' help_url: https://docs.example.com/errors#MISSING_REQUIRED_PARAMETER properties: errors: items: $ref: '#/components/schemas/bad_request_error_response_errors_inner' type: array provider_interaction: $ref: >- #/components/schemas/document_submission_response_provider_interaction type: object 500_error_response: description: An unexpected error occurred while processing your request. properties: message: description: A human-readable description of the unexpected error encountered. example: An unexpected error occurred while processing your request. type: string provider_interaction: $ref: >- #/components/schemas/document_submission_response_provider_interaction required: - message main_document: description: >- Represents an invoice or credit note document to be validated and submitted via the e-invoicing provider. properties: id: description: >- A unique identifier for the document being submitted. This typically represents the invoice number or credit note number generated by Chargebee. type: string type: description: Type of document, either an invoice or a credit note. enum: - INVOICE - CREDIT_NOTE type: string issue_date: description: The date when the document was issued. Format "YYYY-MM-DD" format: date type: string tax_date: description: The date used to determine tax. Format "YYYY-MM-DD" format: date type: string currency_code: description: >- The currency code [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217) for the document. type: string due_date: description: The date when the payment is due. Format "YYYY-MM-DD". format: date type: string amount: description: Total payable amount for the document, including taxes. type: number note: description: >- A textual note that gives unstructured information that is relevant to the Document as a whole. Such as the reason for any correction or assignment note in case the document has been factored. type: string billing_reference: description: >- A group of business terms providing information on one or more preceding invoices. This enhances traceability in workflows where a document is linked to earlier billing records. For credit notes this is essential as they must reference the original invoice they amend. items: $ref: '#/components/schemas/main_document_billing_reference_inner' required: - invoice_document_reference type: array accounting_supplier_party: $ref: '#/components/schemas/main_document_accounting_supplier_party' accounting_customer_party: $ref: '#/components/schemas/main_document_accounting_customer_party' payment_means: description: A list of payment methods with corresponding payment details. items: $ref: '#/components/schemas/payment_means' type: array lines: items: $ref: '#/components/schemas/main_document_lines_inner' type: array tax_total: $ref: '#/components/schemas/main_document_tax_total' overrides: $ref: '#/components/schemas/overrides' required: - accounting_customer_party - accounting_supplier_party - amount - currency_code - dueDate - id - issue_date - lines - tax_date - tax_total - type type: object application_response_document: description: >- Represents an application response document to be validated and submitted via the e-invoicing provider. properties: id: type: string type: description: >- The document type discriminator indicating this is an application response. enum: - APPLICATION_RESPONSE type: string issue_date: format: date type: string sender_party: $ref: '#/components/schemas/application_response_document_sender_party' receiver_party: $ref: '#/components/schemas/application_response_document_sender_party' document_response: $ref: '#/components/schemas/application_response_document_document_response' overrides: $ref: '#/components/schemas/overrides' required: - document_response - id - issue_date - receiver_party - sender_party - type type: object document_submission_response_provider_interaction: description: > Captures the interaction between the adapter and the external e-invoicing provider. Includes both the outbound request details and the inbound response received from the provider. Intended for internally hosted adapters for audit and traceability of SPI transactions. example: request: body: '{}' response: status_code: 0 body: '{}' properties: request: $ref: >- #/components/schemas/document_submission_response_provider_interaction_request response: $ref: >- #/components/schemas/document_submission_response_provider_interaction_response required: - request - response type: object bad_request_error_response_errors_inner: properties: code: description: >- The error codes classify the type of exception that occurred during processing the request. enum: - INVALID_OPERATION - SERVICE_EXCEPTION - SERVICE_UNAVAILABLE - SERVICE_LIMIT_EXCEEDED - MISSING_REQUIRED_DATA - INVALID_DATA type: string message: description: A short message describing the reason for the error. type: string help_url: description: >- The link to the documentation for more information about the error and the corrective action. format: uri type: string required: - message type: object main_document_billing_reference_inner: properties: invoice_document_reference: $ref: >- #/components/schemas/main_document_billing_reference_inner_invoice_document_reference type: object main_document_accounting_supplier_party: description: >- Party responsible for issuing the document (that is, the supplier). This represents the legal entity or business that creates the invoice and bears responsibility for delivering goods or services. properties: name: description: Name of the supplier party. type: string address: $ref: '#/components/schemas/address' tax_scheme: description: List of tax identifiers associated with the supplier. items: $ref: '#/components/schemas/tax_scheme' type: array legal_entity: $ref: '#/components/schemas/party_legal_entity' required: - address - legalEntity - taxScheme type: object main_document_accounting_customer_party: description: Party responsible for receiving the invoice (i.e., the customer). properties: name: description: Name of the customer party. type: string address: $ref: '#/components/schemas/address' tax_scheme: description: List of tax identifiers associated. items: $ref: '#/components/schemas/tax_scheme' type: array legal_entity: $ref: '#/components/schemas/party_legal_entity' required: - address - legalEntity - taxScheme type: object payment_means: description: Defines the method and details for payment. properties: code: description: >- The means, expressed as code, for how a payment is expected to be or has been settled. enum: - CREDIT_TRANSFER - ONLINE_PAYMENT_SERVICE - DIRECT_DEBIT type: string payment_id: description: >- A textual value used to establish a link between the payment and the Invoice, issued by the Seller. Used for creditor's critical reconciliation information. This information element helps the Seller to assign an incoming payment to the relevant payment process. type: string payee_financial_account: $ref: '#/components/schemas/payment_means_payee_financial_account' payment_mandate: $ref: '#/components/schemas/payment_means_payment_mandate' card_account: $ref: '#/components/schemas/payment_means_card_account' type: object main_document_lines_inner: properties: id: description: A unique identifier for the individual line within the document. type: string description: description: >- A textual note that gives unstructured information that is relevant to the document. type: string quantity: description: The quantity of items (goods or services) that is charged. type: integer unit_price: description: The unit price for this line. type: number amount: description: The total amount of the line without tax. type: number discount: description: The discount applied to the line. type: number item_code: description: >- The unique identifier (in Chargebee) of the product corresponding to the line. type: string classified_tax_category: description: >- List of tax categories applicable to the invoice line, such as VAT or other indirect taxes. items: $ref: >- #/components/schemas/main_document_lines_inner_classified_tax_category_inner type: array required: - amount - classifiedTaxCategory - description - id - name - quantity type: object main_document_tax_total: description: Represents the total tax details for the document. properties: tax_amount: description: The total tax amount for the document. format: double type: number tax_sub_totals: items: $ref: '#/components/schemas/main_document_tax_total_tax_sub_totals_inner' type: array type: object overrides: description: > Optional structure used to override the standard Chargebee SPI document model fields with a flexible field-value-based approach. This is **typically used by adapters where field mapping is configured manually by the merchant** in the Chargebee UI, instead of relying on pre-defined mappings managed by the provider or Chargebee. When present, the `overrides` object allows the adapter to **entirely ignore** the standard document payload and instead: - Use `field_mapping` to determine where values go in the provider's schema - Use `values` to retrieve the corresponding input data using dot-paths or array-style paths --- - `field_mapping`: A list of mapping rules that define how Chargebee parameter paths (keys from `values`) should be translated to the corresponding field paths in the provider schema. Includes custom fields too which are defined by merchant in chargebee. Each item must include: - `target`: The field path in the e-invoicing provider schema (e.g. `Invoice.cbc:ID`) - One of the below - `source`: A dot-notated field path or array path from the `values` section (e.g. `invoice.id`, `line_items[].tax_category`) - `fixed_value` (optional): Used if the field always has a constant value (e.g. `380` for `InvoiceTypeCode`) - `expr`: An inline expression evaluated against the values object to compute the target field’s value. This is used when the value depends on conditional logic, tax scenarios, payment methods, or other derived rules. - `values`: Each key in this object uses dot-notation to reference the source path, including arrays and nested arrays — for example: invoice.issue_date, line_items[].id, or line_items[].tax_category[].id. - **Scalar values** (e.g., strings, numbers, dates) should be represented as flat keys: ```json { "invoice.id": "INV-10001", "invoice.issue_date": "2025-04-02", "invoice.currency_code": "EUR" } ``` - **Complex types like arrays** (e.g., `line_items`) should be represented as nested JSON: ```json { "line_items": [ { "id": "1", "line_item_tax": [ {"name" : "VAT" }] }, { "id": "2", "line_item_tax": [ {"name" : "Local Tax"}] } ] } ``` This model supports maximum flexibility by separating the actual data values from Chargebee's internal schema structure. It enables provider-specific document construction without tightly coupling the adapter to Chargebee's native schema. properties: country: description: The ISO country code for the scenario. example: DE type: string transaction_type: description: The type of transaction (B2B, B2C, B2G). enum: - B2B - B2C - B2G example: B2B type: string model: description: > Indicates the eInvoicing flow model that governs the document exchange and processing mechanism. Different countries adopt different models based on legal, technical, and administrative mandates. Supported values: - PEPPOL: A standardized, secure eInvoicing network enabling cross-border electronic document exchange between businesses and governments. - EINVOICE: Traditional eInvoicing model where invoices are digitally exchanged between businesses and sometimes stored. - CLEARANCE: Invoices must be pre-approved by a tax authority before they are sent to the buyer. - REPORTING: Invoices are shared with tax authorities after issuance, usually for compliance and audit purposes. - ZUGFERD: A hybrid eInvoicing format used in Germany combining PDF and XML for human and machine readability. - CTC: Continuous Transaction Controls involve real-time or near-real-time invoice validation and transmission to tax authorities. - NEMHANDEL: Denmark’s national infrastructure for eInvoicing that supports secure delivery via specific formats like OIOUBL. - FACE: Spain’s centralized system (FACe/FACeB2B) for routing invoices to government or private recipients. - VERIFACTU: Spain’s mechanism for validating and reporting sales invoices directly to the tax agency. enum: - PEPPOL - EINVOICE - CLEARANCE - REPORTING - ZUGFERD - CTC - NEMHANDEL - FACE - VERIFACTU example: PEPPOL type: string document_type: description: Type of business document. example: ubl-invoice type: string field_mapping: items: $ref: '#/components/schemas/overrides_field_mapping_inner' type: array values: description: > Flattened key-value representation of the data to be mapped using `field_mapping`. Each key in this object uses dot-notation to reference the source path, including arrays and nested arrays — for example: invoice.issue_date, line_items[].id, or line_items[].tax_category[].id. - **Scalar values** (e.g., strings, numbers, dates) should be represented as flat keys: ```json { "invoice.id": "INV-10001", "invoice.issue_date": "2025-04-02", "invoice.currency_code": "EUR" } ``` - **Complex types like arrays** (e.g., `line_items`) should be represented as nested JSON: ```json { "line_items": [ { "id": "1", "line_item_tax": [ {"name" : "VAT" }] }, { "id": "2", "line_item_tax": [ {"name" : "Local Tax"}] } ] } ``` type: object type: object application_response_document_sender_party: properties: legal_entity: $ref: '#/components/schemas/party_legal_entity' required: - legal_entity type: object application_response_document_document_response: properties: response: $ref: >- #/components/schemas/application_response_document_document_response_response document_reference: $ref: >- #/components/schemas/application_response_document_document_response_document_reference required: - document_reference - response type: object document_submission_response_provider_interaction_request: description: >- Details of the HTTP request sent by the adapter to the external provider. example: body: '{}' properties: body: description: > The request payload sent to the provider API, typically serialized as JSON. This should exclude any sensitive or personally identifiable information. type: object type: object document_submission_response_provider_interaction_response: description: Details of the HTTP response received from the external provider. example: status_code: 0 body: '{}' properties: status_code: description: The HTTP status code returned by the provider. type: integer body: description: | The response body returned by the provider. type: object type: object main_document_billing_reference_inner_invoice_document_reference: description: >- A group of business terms providing information on one or more preceding Invoices. properties: id: description: Identifier of the referenced invoice. type: string issue_date: description: Issue date of the referenced invoice. format: date type: string required: - id type: object address: properties: line_1: description: First line of the address. type: string line_2: description: Second line of the address. type: string line_3: description: Third line of the address. type: string zip: description: Postal or ZIP code. type: string city: description: City name. type: string division: description: Division name. type: string country: description: ISO 3166-1 alpha-2 country code. type: string type: object tax_scheme: properties: scheme: description: >- A code identifying the tax regime under which this party is registered—such as VAT, GST, or a region-specific tax scheme. This enables the adapter or e‑invoicing provider to apply the correct tax logic or reporting rules. type: string id: description: >- The tax identification number assigned to the party by the relevant authority (for example, VAT number or legal registration ID). It is used for official identification and compliance in the e‑invoicing process. type: string required: - id - scheme type: object party_legal_entity: description: Legal entity information of the party. properties: registration_name: description: The full formal name by which the party is registered. type: string company_id: description: >- An identifier issued by an official registrar that identifies the party as a legal entity or person. type: string required: - registrationName type: object payment_means_payee_financial_account: description: A group of business terms to specify credit transfer payments. properties: id: description: >- A unique identifier of the financial payment account, at a payment service provider, to which payment should be made. Such as IBAN or BBAN (e.g., IBAN). type: string required: - id type: object payment_means_payment_mandate: description: A group of business terms to specify a direct debit. properties: id: description: >- Unique identifier assigned by the Payee for referencing the direct debit mandate. type: string mandate_type: description: Type of mandate (e.g., SEPA, national DD agreement). type: string type: object payment_means_card_account: description: >- A group of business terms providing information about card used for payment contemporaneous with invoice issuance. properties: primary_account_number_i_d: description: The Primary Account Number (PAN) of the card used for payment. type: string card_holder_name: description: The name of the payment card holder. type: string network_id: description: The identifier of the card network. (e.g., VISA, MasterCard). type: string type: object main_document_lines_inner_classified_tax_category_inner: properties: percentage: description: >- The tax rate percentage applicable to this tax category (e.g., 19 for 19% VAT). type: number category: description: A code or label identifying the type of tax category. type: string country: description: >- The ISO 3166-1 alpha-2 country code where the tax category is applicable (e.g., DE for Germany). type: string type: object main_document_tax_total_tax_sub_totals_inner: properties: taxable_amount: description: Total taxable amount for the category. format: double type: number tax_amount: description: Total Tax amount for the category format: double type: number percentage: description: The tax rate percentage applied to the taxable amount. format: double type: number country: description: The country code where the tax applies. type: string category: description: The category of tax applied (e.g., VAT). type: string type: object overrides_field_mapping_inner: properties: target: description: Path in the provider schema where the value should be mapped example: Invoice.cbc:ID type: string source: description: Dot-path pointing to a field in `values` example: invoice.id type: string fixed_value: description: Static value if applicable example: '380' type: string expr: description: CEL expression evaluated against `values` type: string required: - target type: object application_response_document_document_response_response: properties: status: enum: - REJECTED - MESSAGE_ACKNOWLEDGEMENT - ACCEPTED - IN_PROCESS - UNDER_QUERY - CONDITIONALLY_ACCEPTED - PAID type: string note: type: string required: - status type: object application_response_document_document_response_document_reference: properties: id: type: string required: - id type: object securitySchemes: ApiKeyAuth: in: header name: Authorization type: apiKey ````