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: /credentials/validate: post: description: This endpoint is used to validate the credentials used to call the Service Provider. operationId: validateCredentials parameters: - description: Merchant's domain name will be sent by Chargebee in: header name: merchant_id required: false schema: type: string - description: Unique id of the request will be sent by Chargebee in: header name: trace_id required: false schema: type: string responses: "200": content: application/json: example: status: VALID schema: $ref: '#/components/schemas/CredentialValidationResponse' description: Authentication succeeded. "401": content: application/json: example: status: INVALID schema: $ref: '#/components/schemas/CredentialValidationResponse' description: Authentication failed. "429": description: Too many requests. "500": content: application/json: example: message: Unexpected error during processing the request. schema: $ref: '#/components/schemas/BasicErrorResponse' description: Unexpected error while processing request. "503": content: application/json: example: status: DOWN version: 1.0.0 description: The service is unhealthy. Several components are down. components: - id: app-db-memory name: Application Database Memory Usage type: DATABASE status: UP - id: adapter-server name: Adapter API Server type: ADAPTER status: DOWN - id: service-server name: API Server type: API status: DOWN time: 2022-11-01T10:42:08.131+05:30 schema: $ref: '#/components/schemas/HealthCheckResponse' description: Service is unhealthy. summary: Validate credentials tags: - Authentication x-accepts: application/json /einvoicing/activations: get: description: |2 Retrieves either: - A list of country-level e-invoicing activations configured at the connected e-invoicing provider, or - A list of business entities configured at the provider, depending on the query parameters used. Each activation represents the provider's capability to support e-invoicing in a specific country and model for a given business entity. **Business Entity Concept** In Chargebee, a *business entity* represents a business unit or brand under the merchant's organization. Refer [here](https://apidocs.chargebee.com/docs/api/business_entities) for more details. In this SPI, a business entity corresponds to the closest equivalent in the provider's system (for example, a company, or tenant). **Modes of Operation** - When called **without parameters**, returns all activations across business entities (if supported by the provider). - When called with `business_entity_id`, returns activations for that specific business entity. - When called with `mode=business_entities`, returns a list of business entities that are active or configured in the provider. This endpoint enables Chargebee to: - Identify e-invoicing capabilities available for activation. - Fetch business entity lists for provider configuration workflows. - Retrieve activation details filtered by a specific business entity during country-level setup. **Example use cases** - During integration setup: `GET /einvoicing/activations?mode=business_entities` - During country configuration: `GET /einvoicing/activations?business_entity_id=` operationId: listActivations parameters: - description: | Filters activations for a specific business entity. In Chargebee, a *business entity* represents a business unit or brand under the merchant's organization. In this SPI, the `business_entity_id` refers to the corresponding identifier in the e-invoicing provider’s system (for example, a company or tenant ID). When provided, the adapter must return only the activations that belong to the specified business entity. explode: true in: query name: business_entity_id required: false schema: type: string style: form - description: "Filters activations by country.\n \nThe value must be a two-letter\ \ ISO 3166-1 alpha-2 country code\n(for example, `DE`, `FR`, `IT`).\n \n\ When provided, the adapter must return only the activations that\nare applicable\ \ for the specified country.\n \nThis parameter is typically used during\ \ country-level e-invoicing\nconfiguration to determine whether a provider\ \ supports e-invoicing\nfor a given country and business ent\n" explode: true in: query name: country required: false schema: maxLength: 2 minLength: 2 type: string style: form - description: | Optional mode for controlling the response type: - `business_entities`: Returns list of Business Entities. - `activations` (default): Returns list of activations. explode: true in: query name: mode required: false schema: enum: - business_entities - activations type: string style: form responses: "200": content: application/json: examples: Business Entities response: summary: Response when listing companies value: business_entities: - id: 595e13fd-68b0-40c2-ade3-9780ce339d97 display_name: Acme BE - id: a3f7b451-29f0-42e0-8e4d-927c0ff19de7 display_name: Beta GmbH Activations response: summary: Response when listing activations for a company value: activations: - id: 02083517-408f-4174-8c4d-42b029162f9c business_entity: id: 595e13fd-68b0-40c2-ade3-9780ce339d97 display_name: Acme Germany status: code: COMPLETED message: Activation completed successfully. country_activations: - model: PEPPOL country: DE einvoicing_type: B2B supported_document_types: - ubl-invoice - ubl-creditnote - ubl-applicationresponse - id: 02083517-408f-4174-8c4d-42b029162f9c business_entity_id: id: 595e13fd-68b0-40c2-ade3-9780ce339d97 display_name: Acme Germany status: code: PENDING message: Activation pending. country_activations: - model: ZUGFERD country: DE einvoicing_type: B2B supported_document_types: - ubl-invoice - ubl-creditnote schema: $ref: '#/components/schemas/listActivations_200_response' description: A list of activations "401": description: Unauthorized "403": description: Forbidden "404": description: Not found "500": content: application/json: schema: $ref: '#/components/schemas/500_error_response' description: Unexpected error while processing request. summary: Retrieve a list of Activations. tags: - Activations x-codeSamples: - lang: cURL label: Integration setup – list companies source: | curl --request GET \ --url https://partner.app.com/einvoicing/activations?mode=companies \ --header 'Content-Type: application/json' \ --header 'Authorization: {"api_key": … }' - lang: cURL label: Country configuration – list activations for one company source: | curl --request GET \ --url https://partner.app.com/einvoicing/activations?business_entity_id=595e13fd-68b0-40c2-ade3-9780ce339d97 \ --header 'Content-Type: application/json' \ --header 'Authorization: {"api_key": … }' - lang: cURL label: Invoice rejected (includes related application response) source: | curl --request POST \ --url https://{domain}.chargebee.com/api/v2/invoices/{document_id}/einvoice_status \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'einvoicing_provider_id=avalara' \ --data-urlencode 'status=REJECTED' \ --data-urlencode 'timestamp=2025-09-04T08:17:30.112Z' \ --data-urlencode 'related_documents[0][document_id]=appresp_7gH1KLM' \ --data-urlencode 'related_documents[0][document_type]=ubl-applicationresponse' \ --data-urlencode 'related_documents[0][status]=SUCCESS' \ --data-urlencode 'related_documents[0][flow]=INBOUND' \ --data-urlencode 'related_documents[0][timestamp]=2025-09-04T08:17:23.380Z' \ --data-urlencode 'related_documents[0][provider_response]={"source":"avalara","received_at":"2025-12-29T12:17:47.791Z","payload":{"id":"ad110f2d-9d0a-4435-a8ea-a36caaceb8c7","companyId":"304382fd-1268-4e7b-86db-a8d51ff309d5","status":"Complete"}}' x-accepts: application/json /einvoicing/data_input_fields: get: description: | This optional SPI endpoint is used to retrieve the required and optional data input fields for various e-invoicing scenarios supported by the provider. Each scenario is defined by a unique combination of country, e-invoicing network, and transaction type (B2B, B2C, or B2G). Implementation of this endpoint is recommended only if the e-invoicing provider requires merchant to configure field mappings themselves, rather than relying on predefined mappings managed by the provider or Chargebee. Within Chargebee, this endpoint is invoked during the e-invoicing setup workflow, when a user maps fields between the provider’s schema and Chargebee’s internal data model for a specific combination of country, network, and transaction type. Once this configuration is complete, the resulting field mappings are included in the document submission request and passed to the adapter via the field_mapping parameter, enabling the adapter to transform the SPI-compliant payload into the provider’s required format. operationId: getDataInputFields parameters: - description: | The ISO 3166-1 alpha-2 country code representing the country for which the e-invoicing data input fields need to be retrieved. Different countries may have varying e-invoicing requirements. explode: true in: query name: country required: true schema: example: DE type: string style: form - description: | The transaction type for which the data input fields need to be retrieved. Required fields may vary depending on the type: B2B (Business to Business), B2C (Business to Consumer), or B2G (Business to Government). explode: true in: query name: transaction_type required: true schema: enum: - B2B - B2C - B2G example: B2B type: string style: form - description: "Indicates the eInvoicing flow model that governs the document\ \ exchange and processing mechanism. \nDifferent countries adopt different\ \ models based on legal, technical, and administrative mandates.\nSupported\ \ values:\n- PEPPOL: A standardized, secure eInvoicing network enabling\ \ cross-border electronic document exchange between businesses and governments.\n\ - EINVOICE: Traditional eInvoicing model where invoices are digitally exchanged\ \ between businesses and sometimes stored.\n- CLEARANCE: Invoices must be\ \ pre-approved by a tax authority before they are sent to the buyer.\n-\ \ REPORTING: Invoices are shared with tax authorities after issuance, usually\ \ for compliance and audit purposes.\n- ZUGFERD: A hybrid eInvoicing format\ \ used in Germany combining PDF and XML for human and machine readability.\n\ - CTC: Continuous Transaction Controls involve real-time or near-real-time\ \ invoice validation and transmission to tax authorities.\n- NEMHANDEL:\ \ Denmark’s national infrastructure for eInvoicing that supports secure\ \ delivery via specific formats like OIOUBL.\n- FACE: Spain’s centralized\ \ system (FACe/FACeB2B) for routing invoices to government or private recipients.\n\ - VERIFACTU: Spain’s mechanism for validating and reporting sales invoices\ \ directly to the tax agency.\n" explode: true in: query name: model required: true schema: enum: - PEPPOL - EINVOICE - CLEARANCE - REPORTING - ZUGFERD - CTC - NEMHANDEL - FACE - VERIFACTU example: PEPPOL type: string style: form - description: Type of business document. explode: true in: query name: document_type required: true schema: example: ubl-invoice type: string style: form responses: "200": content: application/json: schema: $ref: '#/components/schemas/data_input_fields_response' description: Successfully retrieved the data input fields for the given scenario. "400": content: application/json: example: errors: - code: MISSING_REQUIRED_DATA message: Missing required query parameters. help_url: https://docs.example.com/errors#MISSING_REQUIRED_PARAMETER schema: $ref: '#/components/schemas/error_response' description: Bad Request – The request is malformed or missing required parameters. "401": description: Unauthorized "404": content: application/json: example: errors: - code: NOT_FOUND message: "No data input fields were found for the specified country,\ \ network, and transaction type." help_url: https://docs.example.com/errors#NOT_FOUND schema: $ref: '#/components/schemas/error_response' description: Not Found – The requested country or network does not exist or is not supported. "500": description: Internal Server Error – An error occurred on the server. summary: Retrieves data input fields tags: - Activations x-accepts: application/json /einvoicing/documents: post: 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/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. summary: Submit a document tags: - Documents 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", "country": "DE", "transaction_type": "B2B", "model": "PEPPOL", "document_type": "ubl-invoice", "issue_date": "2025-04-02", "tax_date": "2025-04-02", "currency_code": "EUR", "due_date": "2025-04-30", "amount": 114.0, "status": "PAYMENT_DUE", "taxable_amount": 100.0, "amount_due": 114.0, "total_discount": 0.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_registration_number": "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_registration_number": "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 \\\n --url https://partner.app.com/einvoicing/documents\ \ \\\n --header 'Content-Type: application/json' \\\n --header 'Authorization:\ \ {\"api_key\" : ... }' \\\n --data '{\n \"id\": \"INV-20221607\",\n\ \ \"type\": \"INVOICE\",\n \"country\": \"DE\",\n \"transaction_type\"\ : \"B2B\",\n \"model\": \"PEPPOL\",\n \"document_type\": \"ubl-invoice\"\ ,\n \"issue_date\": \"2025-04-02\",\n \"tax_date\": \"2025-04-02\"\ ,\n \"currency_code\": \"EUR\",\n \"due_date\": \"2025-04-30\",\n\ \ \"amount\": 114.0,\n \"status\": \"PAYMENT_DUE\",\n \"taxable_amount\"\ : 100.0,\n \"amount_due\": 114.0,\n \"total_discount\": 0.0,\n \ \ \"note\": \"Payment due in 28 days.\",\n \"accounting_supplier_party\"\ : {\n \"name\": \"Example Seller GmbH\",\n \"address\": {\n \ \ \"line_1\": \"Hauptstr. 456\",\n \"line_2\": \"Suite 5\",\n\ \ \"zip\": \"50667\",\n \"city\": \"Cologne\",\n \"\ country\": \"DE\"\n },\n \"tax_registration_number\": \"DE987654321\"\ \n },\n \"accounting_customer_party\": {\n \"name\": \"Example\ \ Buyer GmbH\",\n \"address\": {\n \"line_1\": \"Berliner Str.\ \ 123\",\n \"line_2\": \"2nd Floor\",\n \"zip\": \"10115\"\ ,\n \"city\": \"Berlin\",\n \"country\": \"DE\"\n },\n\ \ \"tax_registration_number\": \"DE123456789\"\n },\n \"payment_means\"\ : [\n {\n \"code\": \"ONLINE_PAYMENT_SERVICE\",\n \"\ payment_id\": \"PAY-2024-00987\",\n \"card_account\": {\n \ \ \"primary_account_number_id\": \"4111********1111\",\n \"card_holder_name\"\ : \"Jane Smith\",\n \"network_id\": \"MASTERCARD\"\n }\n\ \ }\n ],\n \"lines\": [\n {\n \"id\": \"1\",\n \ \ \"description\": \"Consulting Services - April\",\n \"quantity\"\ : 1,\n \"unit_price\": 100.0,\n \"amount\": 100.0,\n \ \ \"item_code\": \"CONS-APRIL\",\n \"classified_tax_category\"\ : [\n {\n \"percentage\": 14,\n \"category\"\ : \"VAT\",\n \"country\": \"DE\"\n }\n ]\n \ \ }\n ],\n \"tax_total\": {\n \"tax_amount\": 14.0,\n \ \ \"tax_sub_totals\": [\n {\n \"taxable_amount\": 100.0,\n\ \ \"tax_amount\": 14.0,\n \"percentage\": 14,\n \ \ \"country\": \"DE\",\n \"category\": \"VAT\"\n }\n\ \ ]\n },\n \"overrides\": {\n \"country\": \"DE\", \n \ \ \"transaction_type\": \"B2B\",\n \"model\": \"PEPPOL\",\n \ \ \"document_type\": \"ubl-invoice\",\n \"field_mapping\": [\n \ \ {\n \"target\": \"Invoice.cbc:ID\",\n \"source\"\ : \"invoice.id\"\n },\n {\n \"target\": \"Invoice.cbc:IssueDate\"\ ,\n \"source\": \"invoice.issue_date\"\n },\n {\n\ \ \"target\": \"Invoice.cbc:InvoiceTypeCode\",\n \"fixed_value\"\ : \"380\"\n },\n {\n \"target\": \"Invoice.cbc:DocumentCurrencyCode\"\ ,\n \"source\": \"invoice.currency_code\"\n },\n \ \ {\n \"target\": \"Invoice.cac:AccountingSupplierParty.cac:Party.cac:PostalAddress.cac:Country.cbc:IdentificationCode\"\ ,\n \"source\": \"business.address.country\"\n },\n \ \ {\n \"target\": \"Invoice.cac:AccountingCustomerParty.cac:Party.cac:PostalAddress.cac:Country.cbc:IdentificationCode\"\ ,\n \"source\": \"customer.billing_address.country\"\n },\n\ \ {\n \"target\": \"Invoice.cac:AccountingCustomerParty.cac:Party.cac:PartyIdentification.cbc:ID.@schemeID\\\ \"\",\n \"source\": \"custom_fields[cf_einvoice_scheme_id]\"\n\ \ },\n {\n \"target\": \"Invoice.cac:TaxTotal.cbc:TaxAmount\"\ ,\n \"source\": \"invoice.tax_total\"\n },\n {\n\ \ \"target\": \"Invoice.cbc:Note\",\n \"source\": \"invoice.note\"\ \n },\n {\n \"target\": \"Invoice.cac:InvoiceLine.cbc:ID\"\ ,\n \"source\": \"line_items[].id\"\n },\n {\n \ \ \"target\": \"Invoice.cac:InvoiceLine.cbc:InvoicedQuantity\",\n\ \ \"source\": \"line_items[].quantity\"\n },\n {\n\ \ \"target\": \"Invoice.cac:InvoiceLine.cbc:InvoicedQuantity.@unitCode\"\ ,\n \"source\": \"line_items[].unit_code\"\n },\n \ \ {\n \"target\": \"Invoice.cac:InvoiceLine.cbc:LineExtensionAmount\"\ ,\n \"source\": \"line_items[].amount\"\n },\n {\n\ \ \"target\": \"Invoice.cac:InvoiceLine.cbc:LineExtensionAmount.@currencyID\"\ ,\n \"source\": \"invoice.currency_code\"\n },\n \ \ {\n \"target\": \"Invoice.cac:InvoiceLine.cac:Item.cbc:Name\"\ ,\n \"source\": \"line_items[].description\"\n },\n \ \ {\n \"target\": \"Invoice.cac:InvoiceLine.cac:Item.cac:ClassifiedTaxCategory.cbc:ID\"\ ,\n \"expr\": \"li.tax_rate > 0.0 && (!has(li.tax_exempt_reason)\ \ || li.tax_exempt_reason == '') ? 'S' \n :li.tax_rate == 0.0\ \ && li.tax_exempt_reason == 'ZERO_RATED' ? 'Z' \n :li.tax_rate\ \ == 0.0 && li.tax_exempt_reason == 'EXEMPT' ? 'E' \n :li.tax_rate\ \ == 0.0 && li.tax_exempt_reason == 'REVERSE_CHARGE' ? 'AE' \n \ \ :li.tax_rate == 0.0 && li.tax_exempt_reason == 'OUTSIDE_SCOPE' ? 'O'\ \ :\\n''\"\n },\n {\n \"target\": \"Invoice.cac:InvoiceLine.cac:Item.cac:ClassifiedTaxCategory.cac:TaxScheme.cbc:ID\"\ ,\n \"source\": \"line_items[].classified_tax_category[].category\"\ \n },\n {\n \"target\": \"Invoice.cac:InvoiceLine.cac:Price.cbc:PriceAmount\"\ ,\n \"source\": \"line_items[].unit_price\"\n },\n \ \ {\n \"target\": \"Invoice.cac:InvoiceLine.cac:Price.cbc:PriceAmount.@currencyID\"\ ,\n \"source\": \"invoice.currency_code\"\n },\n \ \ {\n \"target\": \"Invoice.cbc:Note\",\n \"source\":\ \ \"invoice.note\"\n }\n ],\n \"values\": {\n \"\ invoice.id\": \"INV-10001\",\n \"invoice.issue_date\": \"2025-04-02\"\ ,\n \"invoice.tax_date\": \"2025-04-02\",\n \"invoice.currency_code\"\ : \"EUR\",\n \"invoice.due_date\": \"2025-04-30\",\n \"invoice.amount\"\ : 114.0,\n \"invoice.note\": \"Payment due in 28 days.\",\n \ \ \"business.address.country\": \"DE\",\n \"customer.billing_address.country\"\ : \"DE\",\n \"custom_fields[cf_einvoice_scheme_id]\": \"9930\",\n\ \ \"invoice.tax_total\": 14.0,\n \"line_items\": [\n \ \ {\n \"id\": \"1\",\n \"description\": \"Consulting\ \ Services - April\",\n \"quantity\": 1,\n \"unit_price\"\ : 100.0,\n \"amount\": 100.0,\n \"item_code\": \"\ CONS-APRIL\",\n \"tax_rate\" : \"14\",\n \"classified_tax_category\"\ : {\n \"percentage\": 14,\n \"category\": \"VAT\"\ ,\n \"country\": \"DE\"\n }\n },\n \ \ {\n \"id\": \"2\",\n \"description\": \"TEST\ \ Consulting Services - April\",\n \"quantity\": 130,\n \ \ \"unit_price\": 1000.0,\n \"amount\": 1005.0,\n \ \ \"item_code\": \"CONS-APRIL\",\n \"tax_rate\" : \"30\"\ ,\n \"classified_tax_category\": {\n \"percentage\"\ : 30,\n \"category\": \"EU VAT\",\n \"country\"\ : \"DE\"\n }\n }\n ]\n }\n }\n }'\n" - 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", "country": "DE", "transaction_type": "B2B", "model": "PEPPOL", "document_type": "ubl-creditnote", "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_registration_number": "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_registration_number": "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 \\\n --url https://partner.app.com/einvoicing/documents\ \ \\\n --header 'Content-Type: application/json' \\\n --header 'Authorization:\ \ {\"api_key\" : ... }' \\\n --data '{\n \"id\": \"CN-20002\",\n \ \ \"type\": \"CREDIT_NOTE\",\n \"country\": \"DE\",\n \"transaction_type\"\ : \"B2B\",\n \"model\": \"PEPPOL\",\n \"document_type\": \"ubl-creditnote\"\ ,\n \"issue_date\": \"2025-04-10\",\n \"tax_date\": \"2025-04-10\"\ ,\n \"currency_code\": \"EUR\",\n \"due_date\": \"2025-04-30\",\n\ \ \"amount\": 50.0,\n \"note\": \"Credit issued for April billing\ \ adjustment.\",\n \"billing_reference\": [\n \"INV-10001\"\n \ \ ],\n \"accounting_supplier_party\": {\n \"name\": \"Example Seller\ \ GmbH\",\n \"address\": {\n \"line_1\": \"Hauptstr. 456\",\n\ \ \"line_2\": \"Suite 5\",\n \"zip\": \"50667\",\n \ \ \"city\": \"Cologne\",\n \"country\": \"DE\"\n },\n \"\ tax_registration_number\": \"DE987654321\"\n },\n \"accounting_customer_party\"\ : {\n \"name\": \"Example Buyer GmbH\",\n \"address\": {\n \ \ \"line_1\": \"Berliner Str. 123\",\n \"line_2\": \"2nd Floor\"\ ,\n \"zip\": \"10115\",\n \"city\": \"Berlin\",\n \"\ country\": \"DE\"\n },\n \"tax_registration_number\": \"DE123456789\"\ \n },\n \"payment_means\": [\n {\n \"code\": \"ONLINE_PAYMENT_SERVICE\"\ ,\n \"payment_id\": \"PAY-2024-01002\",\n \"card_account\"\ : {\n \"primary_account_number_id\": \"4111********2222\",\n \ \ \"card_holder_name\": \"John Doe\",\n \"network_id\":\ \ \"VISA\"\n }\n }\n ],\n \"lines\": [\n {\n \ \ \"id\": \"1\",\n \"description\": \"Refund for overcharge in\ \ April\",\n \"quantity\": 1,\n \"unit_price\": 50.0,\n \ \ \"amount\": 50.0,\n \"item_code\": \"APRIL-REFUND\",\n \ \ \"classified_tax_category\": [\n {\n \"percentage\"\ : 14,\n \"category\": \"VAT\",\n \"country\": \"DE\"\ \n }\n ]\n }\n ],\n \"tax_total\": {\n \"\ tax_amount\": 7.0,\n \"tax_sub_totals\": [\n {\n \"\ taxable_amount\": 50.0,\n \"tax_amount\": 7.0,\n \"percentage\"\ : 14,\n \"country\": \"DE\",\n \"category\": \"VAT\"\n\ \ }\n ]\n },\n \"overrides\": {\n \"country\": \"\ DE\", \n \"transaction_type\": \"B2B\",\n \"model\": \"PEPPOL\"\ ,\n \"document_type\": \"ubl-creditnote\",\n \"field_mapping\"\ : [\n {\n \"target\": \"Creditnote.cbc:ID\",\n \ \ \"source\": \"credit_note.id\"\n },\n {\n \"target\"\ : \"Creditnote.cbc:IssueDate\",\n \"source\": \"credit_note.issue_date\"\ \n },\n {\n \"target\": \"Creditnote.cbc:CreditNoteTypeCode\"\ ,\n \"fixed_value\": \"396\"\n },\n {\n \ \ \"target\": \"Creditnote.cbc:DocumentCurrencyCode\",\n \"source\"\ : \"credit_note.currency_code\"\n },\n {\n \"target\"\ : \"Creditnote.cac:BillingReference\",\n \"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\"\n },\n {\n \"target\": \"Creditnote.cac:AccountingSupplierParty.cac:Party.cbc:EndpointID\"\ ,\n \"source\": \"tax_reg_number\"\n },\n {\n \ \ \"target\": \"Creditnote.cac:AccountingSupplierParty.cac:Party.cac:PostalAddress.cac:Country.cbc:IdentificationCode\"\ ,\n \"source\": \"business.address.country\"\n },\n \ \ {\n \"target\": \"Creditnote.cac:AccountingSupplierParty.cac:Party.cac:PartyLegalEntity.cbc:RegistrationName\"\ ,\n \"source\": \"organization_details.organization_name\"\n \ \ },\n {\n \"target\": \"Creditnote.cac:AccountingCustomerParty.cac:Party.cbc:EndpointID\"\ ,\n \"source\": \"customer.vat_number\"\n },\n {\n\ \ \"target\": \"Creditnote.cac:AccountingCustomerParty.cac:Party.cac:PostalAddress.cac:Country.cbc:IdentificationCode\"\ ,\n \"source\": \"customer.billing_address.country\"\n },\n\ \ {\n \"target\": \"Creditnote.cac:AccountingCustomerParty.cac:Party.cac:PartyLegalEntity.cbc:RegistrationName\"\ ,\n \"source\": \"customer.company\"\n },\n {\n \ \ \"target\": \"Invoice.cac:AccountingCustomerParty.cac:Party.cac:PartyIdentification.cbc:ID.@schemeID\\\ \"\",\n \"source\": \"custom_fields[cf_einvoice_scheme_id]\"\n\ \ },\n {\n \"target\": \"Creditnote.cac:TaxTotal.cbc:TaxAmount\"\ ,\n \"source\": \"credit_note.tax_total\"\n },\n \ \ {\n \"target\": \"Creditnote.cac:TaxTotal.cbc:TaxAmount.@currencyID\"\ ,\n \"source\": \"credit_note.currency_code\"\n },\n \ \ {\n \"target\": \"Creditnote.cac:InvoiceLine.cbc:ID\",\n\ \ \"source\": \"line_items[].id\"\n },\n {\n \ \ \"target\": \"Creditnote.cac:InvoiceLine.cbc:InvoicedQuantity\",\n\ \ \"source\": \"line_items[].quantity\"\n },\n {\n\ \ \"target\": \"Creditnote.cac:InvoiceLine.cbc:InvoicedQuantity.@unitCode\"\ ,\n \"source\": \"line_items[].unit_code\"\n },\n \ \ {\n \"target\": \"Creditnote.cac:InvoiceLine.cbc:LineExtensionAmount\"\ ,\n \"source\": \"line_items[].amount\"\n },\n {\n\ \ \"target\": \"Creditnote.cac:InvoiceLine.cbc:LineExtensionAmount.@currencyID\"\ ,\n \"source\": \"credit_note.currency_code\"\n },\n \ \ {\n \"target\": \"Creditnote.cac:InvoiceLine.cac:Item.cbc:Name\"\ ,\n \"source\": \"line_items[].description\"\n },\n \ \ {\n \"target\": \"Creditnote.cac:InvoiceLine.cac:Item.cac:ClassifiedTaxCategory.cbc:ID\"\ ,\n \"source\": \"line_items[].classified_tax_category[].category\"\ \n },\n {\n \"target\": \"Creditnote.cac:InvoiceLine.cac:Item.cac:ClassifiedTaxCategory.cac:TaxScheme.cbc:ID\"\ ,\n \"source\": \"line_items[].classified_tax_category[].category\"\ \n },\n {\n \"target\": \"Creditnote.cac:InvoiceLine.cac:Price.cbc:PriceAmount\"\ ,\n \"source\": \"line_items[].unit_price\"\n },\n \ \ {\n \"target\": \"Creditnote.cac:InvoiceLine.cac:Price.cbc:PriceAmount.@currencyID\"\ ,\n \"source\": \"credit_note.currency_code\"\n },\n \ \ {\n \"target\": \"Creditnote.cbc:Note\",\n \"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'\"\n }\n ],\n \"values\": {\n \"credit_note.id\"\ : \"CN-20001\",\n \"credit_note.issue_date\": \"2025-04-05\",\n \ \ \"credit_note.tax_date\": \"2025-04-05\",\n \"credit_note.currency_code\"\ : \"EUR\",\n \"credit_note.due_date\": \"2025-04-30\",\n \"\ credit_note.amount\": 140.0,\n \"credit_note.billing_reference\"\ : {\n \"invoice_document_reference\": {\n \"id\": \"\ INV-10001\",\n \"issue_date\": \"2025-04-02\"\n }\n\ \ },\n \"credit_note.note\": \"Refund for April invoice\"\ ,\n \"business.address.country\": \"DE\",\n \"tax_reg_number\"\ : \"DE987654321\",\n \"organization_details.organization_name\":\ \ \"Example Seller GmbH\",\n \"customer.billing_address.country\"\ : \"DE\",\n \"customer.vat_number\": \"DE123456789\",\n \"\ customer.company\": \"Example Buyer GmbH\",\n \"custom_fields[cf_einvoice_scheme_id]\"\ : \"9930\",\n \"credit_note.tax_total\": 40.0,\n \"invoiceResponse\"\ : {\n \"events\": [\n {\n \"responseKey\": \"\ Some Other Event\",\n \"responseValue\": \"Some Value\"\n \ \ },\n {\n \"responseKey\": \"Receipt Message\ \ ID\",\n \"responseValue\": \"RCPT123456\"\n },\n \ \ {\n \"responseKey\": \"Another Event\",\n \ \ \"responseValue\": \"Another Value\"\n }\n ]\n \ \ },\n \"line_items\": [\n {\n \"id\": \"1\"\ ,\n \"description\": \"Reversal of April service\",\n \ \ \"quantity\": 1,\n \"unit_price\": 100.0,\n \ \ \"amount\": 100.0,\n \"unit_code\": \"EA\",\n \"\ classified_tax_category\": {\n \"percentage\": 14,\n \ \ \"category\": \"VAT\",\n \"country\": \"DE\"\n \ \ }\n },\n {\n \"id\": \"2\",\n \ \ \"description\": \"Reversal of consulting charge\",\n \ \ \"quantity\": 1,\n \"unit_price\": 40.0,\n \"\ amount\": 40.0,\n \"unit_code\": \"EA\",\n \"classified_tax_category\"\ : {\n \"percentage\": 30,\n \"category\": \"EU\ \ VAT\",\n \"country\": \"DE\"\n }\n }\n\ \ ]\n }\n }\n }'\n" - 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", "country": "DE", "transaction_type": "B2B", "model": "PEPPOL", "document_type": "ubl-applicationresponse", "issue_date": "2025-04-04", "sender_party": { "name": "Example Sender GmbH", "tax_registration_number": "DE987654321" }, "receiver_party": { "name": "Example Receiver GmbH", "tax_registration_number": "DE123456789" }, "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", "country": "DE", "transaction_type": "B2B", "model": "PEPPOL", "document_type": "ubl-applicationresponse", "issue_date": "2025-04-03", "sender_party": { "name": "Example Sender GmbH", "tax_registration_number": "DE987654321" }, "receiver_party": { "name": "Example Receiver GmbH", "tax_registration_number": "DE123456789" }, "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.name" }, { "target": "ApplicationResponse.cac:ReceiverParty.cac:PartyLegalEntity.cbc:RegistrationName", "source": "application_response.receiver_party.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.name": "Example Sender GmbH", "application_response.receiver_party.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" } } }' x-content-type: application/json x-accepts: application/json /api/v2/invoices/{document_id}/einvoice_status: post: description: | The adapter receives a webhook from the provider, transforms the payload into Chargebee’s standardized schema, and forwards the final document status to this endpoint. Chargebee uses this callback to update internal document tracking states and trigger downstream workflows such as customer notifications or audit logs. This endpoint is **idempotent**, repeated submissions with the same `document_id` and `status` will not result in duplicate processing. Requires an OAuth 2.0 access token authorized via the merchant OAuth flow. The Chargebee merchant must authorize the e-invoicing app via the OAuth flow to allow it to make authenticated POST calls to this endpoint. operationId: einvoicingDocumentStatusCallbackForInvoice parameters: - description: Unique identifier of the submitted document. explode: false in: path name: document_id required: true schema: type: string style: simple requestBody: content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/callback_document_status' required: true responses: "200": description: Callback payload received and validated successfully. No retry required. "202": description: Callback request accepted for asynchronous processing. "400": content: application/json: schema: $ref: '#/components/schemas/einvoicingDocumentStatusCallbackForInvoice_400_response' description: Invalid payload or required fields missing. "401": description: Unauthorized request. Signature validation failed or sender is not allowed. "422": description: "Payload was well-formed but could not be processed (e.g.,\ \ unknown document ID)." "500": description: Internal server error. Retry may be attempted by the sender. security: - authorizationCode: - einvoicing.status servers: - description: Callback server for invoice document status url: "https://{domain}.chargebee.com" summary: Receive document status updates for an invoice tags: - Callbacks x-content-type: application/x-www-form-urlencoded x-accepts: application/json x-codeSamples: - lang: cURL label: Invoice document submission successful source: | curl --request POST \ --url https://{domain}.chargebee.com/api/v2/invoices/{document_id}/einvoice_status \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'einvoicing_provider_id=avalara' \ --data-urlencode 'status=ACCEPTED' \ --data-urlencode 'timestamp=2025-05-23T13:22:50.519Z' --data-urlencode 'provider_response={ "source":"avalara", "received_at":"2025-12-29T12:17:47.791Z", "type":"polling", "payload":{ "id":"ad110f2d-9d0a-4435-a8ea-a36caaceb8c7", "companyId":"304382fd-1268-4e7b-86db-a8d51ff309d5", "status":"Complete", "events":[ {"eventDateTime":"2025-12-29T12:17:47.791","message":"Document started processing"}, {"eventDateTime":"2025-12-29T12:17:47.934","message":"Validations for the submitted document were successful"}, {"eventDateTime":"2025-12-29T12:17:53.063","message":"The document was delivered to the recipient","responseKey":"Receipt Message ID","responseValue":"8b1d6857-d133-4713-9e4e-ca4291e82d7a@einvoicing.sbx.avalara.io"} ] } } }' - lang: cURL label: Invoice document submission failed source: | curl --request POST \ --url https://{domain}.chargebee.com/api/v2/invoices/{document_id}/einvoice_status \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'einvoicing_provider_id=avalara' \ --data-urlencode 'status=FAILED' \ --data-urlencode 'timestamp=2025-05-23T13:22:50.519Z' \ --data-urlencode 'errors[0][code]=MISSING_REQUIRED_DATA' \ --data-urlencode 'errors[0][message]=The request did not contain a required property taxAmount' \ --data-urlencode 'errors[0][help_url]=https://docs.example.com/errors#MISSING_REQUIRED_PARAMETER' - lang: cURL label: Invoice rejected (includes related application response) source: | curl --request POST \ --url https://{domain}.chargebee.com/api/v2/invoices/{document_id}/einvoice_status \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'einvoicing_provider_id=avalara' \ --data-urlencode 'status=REJECTED' \ --data-urlencode 'timestamp=2025-09-04T08:17:30.112Z' \ --data-urlencode 'related_documents[0][document_id]=appresp_7gH1KLM' \ --data-urlencode 'related_documents[0][document_type]=ubl-applicationresponse' \ --data-urlencode 'related_documents[0][status]=SUCCESS' \ --data-urlencode 'related_documents[0][timestamp]=2025-09-04T08:17:23.380Z' \ --data-urlencode 'related_documents[0][provider_response]={"source":"avalara","received_at":"2025-12-29T12:17:47.791Z","payload":{"id":"ad110f2d-9d0a-4435-a8ea-a36caaceb8c7","companyId":"304382fd-1268-4e7b-86db-a8d51ff309d5","status":"Complete"}}' /api/v2/credit_notes/{document_id}/einvoice_status: post: description: | The adapter receives a webhook from the provider, transforms the payload into Chargebee’s standardized schema, and forwards the final document status to this endpoint. Chargebee uses this callback to update internal document tracking states and trigger downstream workflows such as customer notifications or audit logs. This endpoint is **idempotent**, repeated submissions with the same `document_id` and `status` will not result in duplicate processing. Requires an OAuth 2.0 access token authorized via the merchant OAuth flow. The Chargebee merchant must authorize the e-invoicing app via the OAuth flow to allow it to make authenticated POST calls to this endpoint. operationId: einvoicingDocumentStatusCallbackForCreditNote parameters: - description: Unique identifier of the submitted document. explode: false in: path name: document_id required: true schema: type: string style: simple requestBody: content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/callback_document_status' required: true responses: "200": description: Callback payload received and validated successfully. No retry required. "202": description: Callback request accepted for asynchronous processing. "400": content: application/json: schema: $ref: '#/components/schemas/einvoicingDocumentStatusCallbackForInvoice_400_response' description: Invalid payload or required fields missing. "401": description: Unauthorized request. Signature validation failed or sender is not allowed. "422": description: "Payload was well-formed but could not be processed (e.g.,\ \ unknown document ID)." "500": description: Internal server error. Retry may be attempted by the sender. security: - authorizationCode: - write_access servers: - description: Callback server for invoice document status url: "https://{domain}.chargebee.com" summary: Receive document status updates for a credit note tags: - Callbacks x-content-type: application/x-www-form-urlencoded x-accepts: application/json x-codeSamples: - lang: cURL label: Credit note document submission successful source: | curl --request POST \ --url https://{domain}.chargebee.com/api/v2/credit_notes/CN20250205/einvoice_status \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'einvoicing_provider_id=avalara' \ --data-urlencode 'status=ACCEPTED' \ --data-urlencode 'timestamp=2025-05-23T13:22:50.519Z' - lang: cURL label: Credit note document submission failed source: | curl --request POST \ --url https://{domain}.chargebee.com/api/v2/credit_notes/CN20250205/einvoice_status \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'einvoicing_provider_id=avalara' \ --data-urlencode 'status=FAILED' \ --data-urlencode 'timestamp=2025-05-23T13:22:50.519Z' \ --data-urlencode 'errors[0][code]=MISSING_REQUIRED_DATA' \ --data-urlencode 'errors[0][message]=An Invoice shall at least have one VAT breakdown group' \ --data-urlencode 'errors[0][help_url]=https://docs.example.com/errors#MISSING_REQUIRED_PARAMETER' /einvoicing/documents/{document_id}/status: get: description: | Retrieves the current processing status of a document previously submitted to the connected e-invoicing provider. The status provides insights into whether the document has been successfully processed, is still under validation, has failed, or has been rejected by tax authorities or intermediaries. In Chargebee, this endpoint is periodically called to retrieve the latest processing status of the e-invoicing document. While Chargebee primarily relies on the callback listener to receive status updates, this endpoint serves as a fallback mechanism to ensure status synchronization. ' operationId: einvoicingDocumentStatus parameters: - description: The unique identifier assigned to the submitted document by the e‑invoicing provider. explode: false in: path name: document_id required: true schema: type: string style: simple responses: "200": content: application/json: examples: successful_einvoice_document_submission_response: description: A sample response indicating successful e-invoice document status. summary: Successful document status value: document_id: DOC-20250402-0001 status: SUCCESS submission_date: 2025-04-02T07:39:31.815Z provider_response: "{\"source\":\"avalara\",\"received_at\":\"\ 2025-12-29T12:17:47.791Z\",\"payload\":{\"id\":\"ad110f2d-9d0a-4435-a8ea-a36caaceb8c7\"\ ,\"companyId\":\"304382fd-1268-4e7b-86db-a8d51ff309d5\",\"status\"\ :\"Complete\"}}" failed_einvoice_document_submission_response: description: A sample failed document status response due to unregistered VAT number. summary: Failed validation at provider value: document_id: DOC-20250402-0001 status: FAILED processing_details: errors: - code: INVALID_DATA message: The VAT number provided is not registered with the tax authority. help_url: https://docs.example.com/errors#INVALID_DATA schema: $ref: '#/components/schemas/document_status' description: Document status retrieved successfully. "401": description: Unauthorized "403": description: Forbidden "404": content: application/json: schema: $ref: '#/components/schemas/error_response' description: Not found "500": content: application/json: schema: $ref: '#/components/schemas/500_error_response' description: Unexpected error while processing request. summary: Get Document Status tags: - Documents x-accepts: application/json /einvoicing/documents/{document_id}/download: get: description: | Retrieves the document content associated with the provided documentId from the connected e-invoicing provider. A document_id by itself is not always sufficient for the provider to determine which document formats or variants to return. Chargebee includes additional query parameters — such as country, transaction_type, and model — so the adapter can accurately identify and fetch the correct document representations. If the mime_type query parameter is not provided, the adapter MUST retrieve all available document representations for the specified document_id. When a specific mime_type is supplied, the adapter MUST return only the matching representation(s). The document may be returned either as a pre-signed URL or as a direct binary stream (such as a PDF or XML file), depending on the provider’s capabilities and the SPI implementation. In Chargebee, this endpoint is called after the document has been successfully processed either to send it via email to the end customer or when the merchant initiates a download from the Chargebee UI. Implementing this endpoint is MANDATORY to support document retrieval operations. operationId: einvoicingDocumentDownload parameters: - explode: false in: path name: document_id required: true schema: type: string style: simple - description: "Optional MIME type filter for the document representation to\ \ download.\n\nWhen provided, the adapter MUST return only the document(s)\ \ matching this MIME type\n(for example, `application/xml`, `application/pdf`,\ \ or a country-specific UBL MIME type).\n\nWhen omitted, the adapter MUST\ \ attempt to retrieve and return all available representations \nfor the\ \ given document_id from the underlying e-invoicing provider.\n" explode: true in: query name: mime_type required: false schema: example: application/xml type: string style: form - description: | The ISO 3166-1 alpha-2 country code representing the country for which the e-invoicing data input fields need to be retrieved. Different countries may have varying e-invoicing requirements. explode: true in: query name: country required: true schema: example: DE type: string style: form - description: | The transaction type for which the data input fields need to be retrieved. Required fields may vary depending on the type: B2B (Business to Business), B2C (Business to Consumer), or B2G (Business to Government). explode: true in: query name: transaction_type required: true schema: enum: - B2B - B2C - B2G example: B2B type: string style: form - description: "Indicates the eInvoicing flow model that governs the document\ \ exchange and processing mechanism. \nDifferent countries adopt different\ \ models based on legal, technical, and administrative mandates.\nSupported\ \ values:\n- PEPPOL: A standardized, secure eInvoicing network enabling\ \ cross-border electronic document exchange between businesses and governments.\n\ - EINVOICE: Traditional eInvoicing model where invoices are digitally exchanged\ \ between businesses and sometimes stored.\n- CLEARANCE: Invoices must be\ \ pre-approved by a tax authority before they are sent to the buyer.\n-\ \ REPORTING: Invoices are shared with tax authorities after issuance, usually\ \ for compliance and audit purposes.\n- ZUGFERD: A hybrid eInvoicing format\ \ used in Germany combining PDF and XML for human and machine readability.\n\ - CTC: Continuous Transaction Controls involve real-time or near-real-time\ \ invoice validation and transmission to tax authorities.\n- NEMHANDEL:\ \ Denmark’s national infrastructure for eInvoicing that supports secure\ \ delivery via specific formats like OIOUBL.\n- FACE: Spain’s centralized\ \ system (FACe/FACeB2B) for routing invoices to government or private recipients.\n\ - VERIFACTU: Spain’s mechanism for validating and reporting sales invoices\ \ directly to the tax agency.\n" explode: true in: query name: model required: true schema: enum: - PEPPOL - EINVOICE - CLEARANCE - REPORTING - ZUGFERD - CTC - NEMHANDEL - FACE - VERIFACTU example: PEPPOL type: string style: form - description: Type of business document. explode: true in: query name: document_type required: true schema: example: ubl-invoice type: string style: form responses: "200": content: application/json: examples: einvoice_document_download_url_response: description: A sample response with pre-signed S3 URL for document download. summary: Download via pre-signed URL value: document_id: DOC-20250402-0001 request_id: a3d56940-2827-4b87-a229-00d8b95cbe77 documents: - mime_type: application/xml document_url: https://your-bucket.s3.amazonaws.com/invoice-20250402.xml?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLE expires_at: 2025-03-28T09:24:29Z model: PEPPOL einvoice_document_download_stream_response: description: A sample response with Base64-encoded XML and PDF document content. summary: Download via embedded Base64 content value: document_id: DOC-20250402-0001 request_id: a3d56940-2827-4b87-a229-00d8b95cbe77 documents: - mime_type: application/xml document_content: PHh...Q0w+ expires_at: 2025-03-28T09:24:29Z - mime_type: application/pdf document_content: JVBERi0xLjQKJ...CiUlRU9GCg== expires_at: 2025-03-28T09:24:29Z model: PEPPOL schema: $ref: '#/components/schemas/download_document_response' description: Document downloaded successfully. "400": content: application/json: example: errors: - code: INVALID_OPERATION message: The provided mime_type is not supported for this document. help_url: https://docs.example.com/errors#INVALID_OPERATION schema: $ref: '#/components/schemas/error_response' description: Bad Request – The request is invalid or malformed. "401": description: Unauthorized "403": description: Forbidden "404": content: application/json: schema: $ref: '#/components/schemas/error_response' description: Not found "500": content: application/json: schema: $ref: '#/components/schemas/500_error_response' description: Unexpected error while processing request. summary: Download Document tags: - Documents x-accepts: application/json /einvoicing/webhooks/documents/status: post: description: | This endpoint is intended **only for Chargebee-internal hosted adapters**. When the e-invoicing provider (e.g., Avalara) sends a webhook to Chargebee, the Chargebee app forwards the payload *as-is* to this endpoint on the hosted adapter. The adapter is expected to parse and transform the incoming schema according to the provider’s contract and then POST the transformed document status to the callback endpoint Chargebee includes the authorization token in the `X-CB-Authorization` header for the adapter to use while calling back. This keeps the adapter logic stateless and focused on schema transformation. operationId: documentStatusWebhookForwarded requestBody: content: application/json: example: id: 8dd0013d-ac06-4793-94fc-945249f1547c invocationTimestamp: 2025-09-04T08:17:25.504429841 items: - tenantId: 67379e869f31e4e90dfdda27 systemCode: DES eventName: statusChange message: id: f12386ed-77ee-4b57-ac2e-a2905b1d22f4 companyId: bfc169c9-4793-4962-9a3e-24e9b4625168 processDateTime: 2025-09-04T08:17:23.380Z status: Pending documentNumber: PEPPOL-EU-690 documentType: ubl-invoice documentVersion: "2.1" documentDate: 2025-07-01T00:00:00 flow: out countryCode: DE countryMandate: DE-B2B-PEPPOL supplierName: Chargebee Germany customerName: Avalara Europe Ltd. interfaceName: "" signature: value: 4CPe+MK4rf2VIOBSPicH1T0/NeGAyOBURe3gNETVql8= algorithm: SHA-256 schema: additionalProperties: true description: | Arbitrary payload forwarded by Chargebee as received from the e-invoicing provider. Each provider may have its own structure. The adapter must handle the schema transformation. type: object description: Raw webhook payload received from the e-invoicing provider. required: true responses: "200": description: Webhook successfully accepted and forwarded. "400": description: Invalid payload format or missing required properties. "401": description: Unauthorized. "500": description: Adapter failed to process the webhook internally. security: - ApiKeyAuth: [] - CBAuth: [] summary: Receive document status webhook from e-invoicing provider tags: - Webhooks x-content-type: application/json x-accepts: application/json /health: get: description: This endpoint is used to fetch the health status of the Service Provider. operationId: fetchHealth parameters: - description: Merchant's domain name will be sent by Chargebee in: header name: merchant_id required: false schema: type: string - description: Unique id of the request will be sent by Chargebee in: header name: trace_id required: false schema: type: string responses: "200": content: application/json: example: status: UP version: 1.0.0 description: The service is healthy. components: - id: app-db-memory name: Application Database type: DATABASE status: UP - id: adapter-server name: Adapter API Server type: ADAPTER status: UP - id: service-server name: API Server type: API status: UP time: 2022-11-01T10:42:08.131+05:30 schema: $ref: '#/components/schemas/HealthCheckResponse' description: Service is healthy. "429": description: Too many requests. "500": content: application/json: example: message: Unexpected error during processing the request. schema: $ref: '#/components/schemas/BasicErrorResponse' description: Unexpected error while processing request. "503": content: application/json: example: status: DOWN version: 1.0.0 description: The service is unhealthy. Several components are down. components: - id: app-db-memory name: Application Database Memory Usage type: DATABASE status: UP - id: adapter-server name: Adapter API Server type: ADAPTER status: DOWN - id: service-server name: API Server type: API status: DOWN time: 2022-11-01T10:42:08.131+05:30 schema: $ref: '#/components/schemas/HealthCheckResponse' description: Service is unhealthy. summary: Fetch the health status of the Service Provider. tags: - Health x-accepts: application/json components: examples: callback_document_status_success_for_invoice: description: A sample callback notification indicating successful document submission. value: einvoicing_provider_id: avalara status: ACCEPTED timestamp: 2025-05-23T13:22:50.519Z provider_response: | { "source": "avalara", "received_at": "2025-12-29T12:17:47.791Z", "type": "polling", "payload": { "id": "ad110f2d-9d0a-4435-a8ea-a36caaceb8c7", "companyId": "304382fd-1268-4e7b-86db-a8d51ff309d5", "status": "Complete", "events": [ { "eventDateTime": "2025-12-29T12:17:47.791", "message": "Document started processing" }, { "eventDateTime": "2025-12-29T12:17:47.934", "message": "Validations for the submitted document were successful" }, { "eventDateTime": "2025-12-29T12:17:53.063", "message": "The document was delivered to the recipient", "responseKey": "Receipt Message ID", "responseValue": "8b1d6857-d133-4713-9e4e-ca4291e82d7a@einvoicing.sbx.avalara.io" } ] } } provider_references: | [ {"key": "Receipt Message ID", "value": "8b1d6857-d133-4713-9e4e-ca4291e82d7a@einvoicing.sbx.provider.io"}, {"key": "Response Message ID", "value": "8b1d6857-d133-4713-9e4e-ca4291e82d7a@einvoicing.sbx.provider.io"}, {"key": "Receiver ID", "value": "3ed9530e-f2e8-4733-ace8-f868a5e077eb@sbx.provider.io"} ] callback_document_status_success_for_credit_note: description: A sample callback notification indicating successful document submission. value: einvoicing_provider_id: avalara status: ACCEPTED timestamp: 2025-05-23T13:22:50.519Z callback_document_status_failed_for_invoice: description: A sample callback notification indicating document submission failure. value: einvoicing_provider_id: avalara status: FAILED timestamp: 2025-05-23T13:22:50.519Z 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 callback_document_status_failed_for_credit_note: description: A sample callback notification indicating document submission failure. value: einvoicing_provider_id: avalara status: FAILED timestamp: 2025-05-23T13:22:50.519Z errors: - code: MISSING_REQUIRED_DATA message: An Invoice shall at least have one VAT breakdown group help_url: https://docs.example.com/errors#MISSING_REQUIRED_PARAMETER parameters: MerchantId: description: Merchant's domain name will be sent by Chargebee in: header name: merchant_id required: false schema: type: string TraceId: description: Unique id of the request will be sent by Chargebee in: header name: trace_id required: false schema: type: string responses: Error429: description: Too many requests. Error500: content: application/json: example: message: Unexpected error during processing the request. schema: $ref: '#/components/schemas/BasicErrorResponse' description: Unexpected error while processing request. Error503: content: application/json: example: status: DOWN version: 1.0.0 description: The service is unhealthy. Several components are down. components: - id: app-db-memory name: Application Database Memory Usage type: DATABASE status: UP - id: adapter-server name: Adapter API Server type: ADAPTER status: DOWN - id: service-server name: API Server type: API status: DOWN time: 2022-11-01T10:42:08.131+05:30 schema: $ref: '#/components/schemas/HealthCheckResponse' description: Service is unhealthy. schemas: 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 activation: properties: id: description: The unique identifier of the activation type: string business_entity: $ref: '#/components/schemas/activation_business_entity' status: $ref: '#/components/schemas/activation_status' country_activations: items: $ref: '#/components/schemas/country_activation' type: array type: object country_activation: properties: model: $ref: '#/components/schemas/model' country: description: ISO 3166-1 alpha-2 country code where the e-invoicing activation is applicable. type: string einvoicing_type: description: Specifies the type of business transaction for which e-invoicing is applied. enum: - B2B - B2C - B2G type: string supported_document_types: description: | The types of business documents that are supported for this country activation. example: - ubl-invoice - ubl-creditnote - ubl-applicationresponse items: type: string type: array type: object activations_response: properties: activations: items: $ref: '#/components/schemas/activation' type: array type: object business_entities_response: properties: business_entities: description: List of business_entities retrieved from the e-invoicing provider. items: $ref: '#/components/schemas/business_entities_response_business_entities_inner' type: array type: object data_input_fields_response: example: country: DE transaction_type: B2B model: PEPPOL document_type: ubl-invoice fields: - path: Invoice.cbc:ID field_name: cbc:ID description: Unique identifier for the invoice data_type: string documentation_link: "" accepted_values: [] default_value: "" example: INV-1001 inclusion_type: Mandatory - path: Invoice.cbc:Note field_name: cbc:Note description: Optional description or remarks data_type: string documentation_link: "" accepted_values: [] default_value: "" example: B2B Transaction inclusion_type: Optional - path: Invoice/cbc:BuyerReference field_name: cbc:BuyerReference description: | Buyer Reference: An identifier assigned by the Buyer used for internal routing purposes. An invoice must have buyer reference or purchase order reference. data_type: string documentation_link: "" accepted_values: [] default_value: "" example: abs1234 inclusion_type: Conditional condition: null - path: Invoice.cac:InvoiceLine.cbc:LineExtensionAmount field_name: cbc:LineExtensionAmount description: | Invoice line net amount — The total amount of the Invoice line. This amount is net (without VAT), and must be rounded to a maximum of 2 decimals. data_type: number documentation_link: "" accepted_values: [] default_value: "" example: 2145 inclusion_type: Conditional condition: null 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: $ref: '#/components/schemas/model' document_type: description: Type of business document. example: ubl-invoice type: string fields: description: List of input fields with inclusion metadata. items: $ref: '#/components/schemas/data_input_fields_response_fields_inner' type: array type: object document: discriminator: mapping: INVOICE: '#/components/schemas/main_document' CREDIT_NOTE: '#/components/schemas/main_document' APPLICATION_RESPONSE: '#/components/schemas/application_response_document' propertyName: type oneOf: - $ref: '#/components/schemas/main_document' - $ref: '#/components/schemas/application_response_document' type: object 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 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: $ref: '#/components/schemas/model' document_type: description: Type of business document. example: ubl-invoice 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 status: $ref: '#/components/schemas/document_billing_status' taxable_amount: description: Total document amount excluding tax (VAT). type: number amount_due: description: Outstanding balance remaining on the document. type: number total_discount: description: Sum of all discounts applied across line items on the document. 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 custom_fields: allOf: - $ref: '#/components/schemas/custom_fields' description: Invoice or credit note custom field values keyed by API name (e.g. `cf_invoice_reference`). subscription_custom_fields: allOf: - $ref: '#/components/schemas/custom_fields' description: | Subscription custom fields for single-subscription documents (set once at document level). For consolidated / multi-subscription documents, use `lines[].subscription_custom_fields` instead. 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 - amount_due - country - currency_code - due_date - id - issue_date - lines - model - status - tax_date - tax_total - taxable_amount - 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 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: $ref: '#/components/schemas/model' document_type: description: Type of business document. example: ubl-applicationresponse type: string issue_date: format: date type: string sender_party: $ref: '#/components/schemas/application_response_party' receiver_party: $ref: '#/components/schemas/application_response_party' document_response: $ref: '#/components/schemas/application_response_document_document_response' overrides: $ref: '#/components/schemas/overrides' required: - country - document_response - id - issue_date - model - receiver_party - sender_party - type 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: $ref: '#/components/schemas/model' 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`. \n\nEach 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.\n\ \n- **Scalar values** (e.g., strings, numbers, dates) should be represented\ \ as flat keys:\n```json\n{\n \"invoice.id\": \"INV-10001\",\n \"invoice.issue_date\"\ : \"2025-04-02\",\n \"invoice.currency_code\": \"EUR\"\n}\n```\n\n- **Complex\ \ types like arrays** (e.g., `line_items`) should be represented as nested\ \ JSON:\n```json\n{\n \"line_items\": [\n { \"id\": \"1\", \"line_item_tax\"\ : [ {\"name\" : \"VAT\" }] },\n { \"id\": \"2\", \"line_item_tax\"\ : [ {\"name\" : \"Local Tax\"}] }\n ]\n}\n```\n" type: object 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 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 document_status: example: document_id: DOC-20250402-0001 status: SUCCESS submission_date: 2025-04-02T07:39:31.815Z provider_response: "{\"source\":\"avalara\",\"received_at\":\"2025-12-29T12:17:47.791Z\"\ ,\"payload\":{\"id\":\"ad110f2d-9d0a-4435-a8ea-a36caaceb8c7\",\"companyId\"\ :\"304382fd-1268-4e7b-86db-a8d51ff309d5\",\"status\":\"Complete\"}}" properties: document_id: description: The unique identifier assigned to the document by the e-invoicing provider. type: string status: description: The current status of the document submission. enum: - ACCEPTED - FAILED - SUCCESS - IN_PROGRESS - REJECTED - MESSAGE_ACKNOWLEDGEMENT - IN_PROCESS - UNDER_QUERY - CONDITIONALLY_ACCEPTED - PAID type: string submission_date: description: Date and time when the document was submitted. format: date-time type: string processing_details: $ref: '#/components/schemas/error_response' provider_response: description: | JSON string containing an optional array of raw payloads received from the e-invoicing provider that is used for downstream mapping and for audits. The JSON should be an array of objects with the following structure: [{"source": "string", "received_at": "date-time", "payload": {object}}] example: "{\"source\":\"avalara\",\"received_at\":\"2025-12-29T12:17:47.791Z\"\ ,\"payload\":{\"id\":\"ad110f2d-9d0a-4435-a8ea-a36caaceb8c7\",\"companyId\"\ :\"304382fd-1268-4e7b-86db-a8d51ff309d5\",\"status\":\"Complete\"}}" type: string provider_references: description: | Optional JSON array of key-value pairs from the e-invoicing provider (e.g. Receipt Message ID, Response Message ID). Format: [{"key": "string", "value": "string"}, ...] example: "[{\"key\":\"Receipt Message ID\",\"value\":\"3ed9530e-f2e8-4733-ace8-f868a5e077eb@einvoicing.sbx.provider.io\"\ },{\"key\":\"Response Message ID\",\"value\":\"3ed9530e-f2e8-4733-aeffe8-f868a5e077eb@einvoicing.sbx.provider.io\"\ }]" type: string required: - document_id - status type: object download_document_response: example: request_id: a3d56940-2827-4b87-a229-00d8b95cbe77 documents: - mime_type: application/xml document_url: https://provider.com/downloads/invoice-20250402.xml expires_at: 2025-03-28T09:24:29Z model: PEPPOL properties: document_id: type: string request_id: type: string documents: items: $ref: '#/components/schemas/download_document_response_documents_inner' type: array model: $ref: '#/components/schemas/model' required: - document_id - documents type: object 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/error_response_errors_inner' type: array provider_interaction: $ref: '#/components/schemas/document_submission_response_provider_interaction' type: object not_found_error_response: example: errors: - code: NOT_FOUND message: The requested document is not found. help_url: https://docs.example.com/errors#INVALID_OPERATION properties: errors: description: A list of errors explaining why the requested resource was not found. items: $ref: '#/components/schemas/not_found_error_response_errors_inner' type: array required: - errors type: object document_billing_status: description: | Billing status of the invoice or credit note in Chargebee. **Invoice statuses** (when `type` is `INVOICE`): - `PAID` — Indicates a paid invoice. - `POSTED` — Payment is not yet collected and will remain in this state until the due date to indicate the due period. - `PAYMENT_DUE` — Payment is not yet collected and is being retried as per retry settings. - `NOT_PAID` — Payment has not been made and all attempts to collect have failed. - `VOIDED` — Indicates a voided invoice. **Credit note statuses** (when `type` is `CREDIT_NOTE`): - `ADJUSTED` — Indicates an adjustment credit note. - `REFUNDED` — Indicates the credit note has been fully refunded. - `REFUND_DUE` — Indicates a refund is due on the credit note. - `VOIDED` — Indicates a voided credit note. enum: - PAID - POSTED - PAYMENT_DUE - NOT_PAID - VOIDED - ADJUSTED - REFUNDED - REFUND_DUE example: PAYMENT_DUE type: string application_response_party: description: Party information for the sender or receiver of an application response document. properties: name: description: Name of the party. type: string tax_registration_number: description: "Tax registration number of the party (for example VAT / GST\ \ number), when available." type: string 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 custom_fields: additionalProperties: type: string description: | Merchant-defined custom field values keyed by Chargebee API name (for example, `cf_po_number`). Values are serialized as strings. example: cf_po_number: PO-12345 cf_cost_center: CC-42 type: object callback_document_status: properties: einvoicing_provider_id: description: Identifier of the e‑invoicing provider type: string status: description: Current status of the document after processing by the provider. enum: - SUCCESS - IN_PROGRESS - FAILED - ACCEPTED - REJECTED - MESSAGE_ACKNOWLEDGEMENT - IN_PROCESS - UNDER_QUERY - CONDITIONALLY_ACCEPTED - PAID type: string timestamp: description: Timestamp (UTC) in seconds indicating when the status was determined. type: string provider_response: description: | JSON string containing an optional array of raw payloads received from the e-invoicing provider that is used for downstream mapping and for audits. The JSON should be an array of objects with the following structure: [{"source": "string", "received_at": "date-time", "payload": {object}}] example: "{\"source\":\"avalara\",\"received_at\":\"2025-12-29T12:17:47.791Z\"\ ,\"payload\":{\"id\":\"ad110f2d-9d0a-4435-a8ea-a36caaceb8c7\",\"companyId\"\ :\"304382fd-1268-4e7b-86db-a8d51ff309d5\",\"status\":\"Complete\"}}" type: string provider_references: description: | Optional JSON array of key-value pairs returned by the e-invoicing provider (e.g. Receipt Message ID, Response Message ID, Receiver ID). Chargebee stores this in einvoice properties and appends entries on each callback, similar to provider_response. Format: [{"key": "string", "value": "string"}, ...] example: "[{\"key\":\"Receipt Message ID\",\"value\":\"3ed9530e-f2e8-4733-ace8-f868a5e077eb@einvoicing.sbx.avalara.io\"\ },{\"key\":\"Response Message ID\",\"value\":\"3ed9530e-f2e8-4733-aeffe8-f868a5e077eb@einvoicing.sbx.avalara.io\"\ },{\"key\":\"Receiver ID\",\"value\":\"3ed9530e-f2e8-4733-ace8-f868a5e077eb@sbx.avalara.io\"\ }]" type: string errors: description: | Optional list of errors (if any) returned by the provider if status is FAILED. Encoded using Chargebee's form-urlencoded bracket notation, e.g. `errors[0][code]`. items: $ref: '#/components/schemas/callback_error' maxItems: 50 type: array related_documents: description: | Optional list of related (secondary) document status objects, encoded using Chargebee's form-urlencoded bracket notation, e.g. `related_documents[0][document_id]`. Use this to include secondary documents such as `ubl-applicationresponse` that influenced the primary document outcome. Chargebee may store this for diagnostics; it does not change the primary idempotency key. items: $ref: '#/components/schemas/callback_related_document_status' maxItems: 10 type: array required: - status - timestamp type: object callback_error: description: Error details returned by the provider. properties: code: description: Error code identifying the type of error. example: MISSING_REQUIRED_DATA maxLength: 100 type: string message: description: Human-readable error message describing what went wrong. example: The request did not contain a required property maxLength: 500 type: string help_url: description: Optional URL to documentation or help resources for this error. example: https://docs.example.com/errors#MISSING_REQUIRED_PARAMETER format: uri maxLength: 500 type: string required: - message type: object callback_related_document_status: description: Related/secondary document status details. properties: document_id: description: Unique identifier of the related submitted document in Chargebee tracking. maxLength: 100 type: string document_type: description: "Document type of the related document (e.g., ubl-applicationresponse)." example: ubl-applicationresponse maxLength: 100 type: string status: description: Current status of the related document. enum: - SUCCESS - IN_PROGRESS - FAILED type: string flow: description: The direction flow of the related document. enum: - INBOUND - OUTBOUND type: string timestamp: description: Timestamp (UTC) in seconds indicating when the related document status was determined. type: string provider_response: description: | JSON string containing an optional array of raw payloads received from the e-invoicing provider that is used for downstream mapping and for audits. The JSON should be an array of objects with the following structure: [{"source": "string", "received_at": "date-time", "payload": {object}}] example: "{\"source\":\"avalara\",\"received_at\":\"2025-12-29T12:17:47.791Z\"\ ,\"payload\":{\"id\":\"ad110f2d-9d0a-4435-a8ea-a36caaceb8c7\",\"companyId\"\ :\"304382fd-1268-4e7b-86db-a8d51ff309d5\",\"status\":\"Complete\"}}" type: string provider_references: description: | Optional JSON array of key-value pairs for this related document (e.g. Receipt Message ID, Response Message ID). Chargebee stores this in the artifact properties and appends entries on each callback, similar to provider_response. Format: [{"key": "string", "value": "string"}, ...] example: "[{\"key\":\"Receipt Message ID\",\"value\":\"3ed9530e-f2e8-4733-ace8-f868a5e077eb@einvoicing.sbx.avalara.io\"\ },{\"key\":\"Response Message ID\",\"value\":\"3ed9530e-f2e8-4733-aeffe8-f868a5e077eb@einvoicing.sbx.avalara.io\"\ }]" type: string errors: description: | Provider errors for the related document (stringified JSON array). Present when `status=FAILED`. example: | [{"code":"AR_VALIDATION_FAILED","message":"Invalid response code"}] type: string required: - document_id - document_type - flow - status - timestamp 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 CredentialValidationResponse: example: status: null properties: status: $ref: '#/components/schemas/CredentialStatus' required: - status type: object CredentialStatus: description: The status of the credentials used for authentication. enum: - VALID - INVALID type: string BasicErrorResponse: additionalProperties: false description: The basic error response containing the error message and the help documentation link. properties: message: description: The description of the error with details about it's cause. example: Invalid Credentials maxLength: 250 type: string helpUrl: description: The link to the documentation for more information about the error and the corrective action. example: https://apidocs.chargebee.com#Authentication format: uri type: string required: - message type: object HealthCheckResponse: example: components: - endpoints: - endpoints - endpoints name: name description: description id: id type: OTHER status: null - endpoints: - endpoints - endpoints name: name description: description id: id type: OTHER status: null description: description time: 2000-01-23T04:56:07.000+00:00 version: version status: null properties: version: minLength: 1 type: string description: description: The description of the health status returned by the Service Adapter. maxLength: 250 type: string status: $ref: '#/components/schemas/HealthStatus' components: description: List of health status details for each component reported by the Service Adapter. items: $ref: '#/components/schemas/HealthCheckComponent' type: array time: description: The timestamp of the health status reported by the Service Adapter. format: date-time type: string required: - components - status - time type: object HealthStatus: description: The status of a specific component reported by the Service Adapter. enum: - UP - DOWN - WARN type: string HealthCheckComponent: description: The health status details of a specific component reported by the Service Adapter. example: endpoints: - endpoints - endpoints name: name description: description id: id type: OTHER status: null properties: id: description: The id of the component. maxLength: 50 type: string name: description: The name of the component. maxLength: 150 type: string type: description: | The type of component affected when `status` is `WARN` or `DOWN`. The possible values are: - `ADAPTER`: The reported status is for the Service Adapter. - `API`: The reported status is for the Service Provider. - `DATABASE`: The reported status is for a database dependency of the Service Provider. - `SYSTEM`: The reported status is for any other known system component such as cache or gateway. - `OTHER`: The reported status is either for a component that does not belong to the types described above or the source of the issue is unknown. enum: - OTHER - SYSTEM - API - ADAPTER - DATABASE type: string description: description: The detailed status of the component. maxLength: 250 type: string status: $ref: '#/components/schemas/HealthStatus' endpoints: description: "When the `status` of the component is not `UP`, then the list\ \ of endpoints affected." items: type: string type: array required: - id - name - status - type type: object listActivations_200_response: oneOf: - $ref: '#/components/schemas/activations_response' - $ref: '#/components/schemas/business_entities_response' einvoicingDocumentStatusCallbackForInvoice_400_response: properties: errors: items: $ref: '#/components/schemas/callback_error' type: array related_documents: items: $ref: '#/components/schemas/callback_related_document_status' type: array type: object activation_business_entity: properties: id: description: The unique identifier for the company type: string display_name: description: The display name of the company type: string type: object activation_status: properties: code: description: The current status of the activation as reported by the e-invoicing provider. enum: - COMPLETED - FAILED - PENDING type: string message: description: A detailed message describing the activation status. type: string type: object business_entities_response_business_entities_inner: properties: id: description: The unique identifier of the business entity. example: 595e13fd-68b0-40c2-ade3-9780ce339d97 type: string display_name: description: The display name of the business entity. example: Acme BE type: string type: object data_input_fields_response_fields_inner: properties: path: description: Path of the field in the final XML/UBL or JSON structure (as per provider specification). example: Invoice.cbc:ID type: string field_name: description: Canonical or local name of the field. example: cbc:ID type: string description: description: Description of what the field represents. example: Unique identifier for the invoice. type: string data_type: description: Type of data expected. enum: - string - number - date - boolean type: string documentation_link: description: External documentation reference for the field (if available). example: https://docs.peppol.eu/poacc/billing/3.0/syntax/ubl-invoice/cbc-ID type: string accepted_values: description: Enumerated or acceptable values for the field (if applicable). example: [] items: type: string type: array default_value: description: Default value to use if none is provided. example: "" type: string example: description: Example value for the field. example: INV-1001 type: string inclusion_type: description: | Denotes whether this field is required, optional, or conditional. - `Mandatory`: Must be provided - `Optional`: Can be skipped without affecting processing - `Conditional`: Required under specific conditions enum: - Mandatory - Optional - Conditional type: string condition: description: Optional condition object for Conditional fields. type: object required: - data_type - field_name - inclusion_type - path 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 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_registration_number: description: "Tax registration number of the supplier (for example VAT /\ \ GST number), when available." type: string required: - address 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_registration_number: description: "Tax registration number of the customer (for example VAT /\ \ GST number), when available." type: string custom_fields: allOf: - $ref: '#/components/schemas/custom_fields' description: Customer custom field values keyed by API name (e.g. `cf_tax_id`). required: - address 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_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 subscription_custom_fields: allOf: - $ref: '#/components/schemas/custom_fields' description: | Subscription custom fields for this line's subscription. Present on consolidated / multi-subscription documents. For single-subscription documents, see `main_document.subscription_custom_fields`. product_custom_fields: allOf: - $ref: '#/components/schemas/custom_fields' description: Product / item-price custom field values for this line keyed by API name (e.g. `cf_hs_code`). 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_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 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 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 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 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 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 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 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 download_document_response_documents_inner: properties: mime_type: description: The MIME type of the document. type: string document_url: description: Presigned URL to access the document. This param will be preferred if found over document_content. format: uri type: string document_content: description: Base64-encoded document content if URL is not available. format: byte type: string expires_at: description: The time until which the document URL is valid. example: 2025-03-28T09:24:29Z format: date-time type: string required: - mime_type type: object 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 - NOT_FOUND 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 not_found_error_response_errors_inner: properties: code: description: Application-specific error code enum: - NOT_FOUND 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: - code - message type: object securitySchemes: ApiKeyAuth: in: header name: Authorization type: apiKey CBAuth: in: header name: X-CB-Authorization type: apiKey authorizationCode: flows: authorizationCode: authorizationUrl: https://app.chargebee.com/oauth2/authorize scopes: write_access: Post e-invoicing document status to Chargebee tokenUrl: https://app.chargebee.com/oauth2/token type: oauth2