> ## Documentation Index > Fetch the complete documentation index at: https://spidocs.chargebee.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieves data input fields > 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. ## OpenAPI ````yaml get /einvoicing/data_input_fields openapi: 3.0.0 info: description: > ## E-invoicing Service Provider Interface (SPI) - Overview Chargebee streamlines e-invoicing compliance across regions by facilitating the following operations throughout the billing lifecycle. 1) Retrieve E-invoicing Activations: - Retrieves the list of country and network activations that are configured in the connected e-invoicing provider platform. - Each activation reflects a country and e-invoicing network that has been set up and made available by the provider. - Chargebee uses this operation during provider enablement to determine which activations can be offered to merchants. 2) Document Submission: - Submits invoices and credit notes to external e-invoicing systems for validation, compliance processing, and delivery to tax authorities or trading partners. 3) Status Tracking: - Supports asynchronous document lifecycle tracking through webhook notifications sent by the e-invoicing adapter. These updates reflect real-time status changes as documents move through validation, compliance, and regulatory delivery stages. - Allows on-demand status checks to retrieve the latest processing state of submitted documents, ensuring continued visibility even if webhook delivery is delayed or disrupted. 4) Final Document Retrieval: - Retrieves finalized and regulator-approved documents for archiving, auditing or customer-facing use. Chargebee leverages external e-invoicing services to execute these operations effectively. These external e-invoicing servies are the certified vendors offering APIs to handle e-invoicing compliance and document exchange with tax authorities. ## The Role of the E-invoicing Adapter App: To connect with external e-invoicing systems, Chargebee uses an E-invoicing Adapter App - a bridge that enables secure and standardized communication between Chargebee and the e-invoicing system. This communication is governed by the E-invoicing Service Provider Interface (SPI). ## Building an E-invoicing Adapter App To integrate an e-invoicing system with Chargebee, you must implement the E-invoicing SPI by developing an adapter app. This is required in the following scenarios: - As an E-invoicing Provider: - Connect your compliance platform to Chargebee so merchants can automatically submit billing documents in a regulator-approved format. - As a System Integrator: - Build a connector that bridges a third-party e-invoicing provider and Chargebee, enabling seamless integration for merchants. By implementing the E-invoicing SPI, you enable Chargebee to support global regulatory compliance through a scalable and region-agnostic architecture. title: E-Invoicing Service Provider Interface version: 1.0.0 servers: - description: Production server (replace with actual service URL) url: https://api.example.com - description: Sandbox server for testing url: https://sandbox.example.com security: - ApiKeyAuth: [] tags: - description: Operations related to e-invoicing activations name: Activations - description: Operations related to e-invoicing documents name: Documents paths: /einvoicing/data_input_fields: get: tags: - Activations summary: Retrieves data input fields 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. 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. 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/bad_request_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/not_found_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. components: schemas: 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: description: > Indicates the eInvoicing flow model that governs the document exchange and processing mechanism. Different countries adopt different models based on legal, technical, and administrative mandates. Supported values: - PEPPOL: A standardized, secure eInvoicing network enabling cross-border electronic document exchange between businesses and governments. - EINVOICE: Traditional eInvoicing model where invoices are digitally exchanged between businesses and sometimes stored. - CLEARANCE: Invoices must be pre-approved by a tax authority before they are sent to the buyer. - REPORTING: Invoices are shared with tax authorities after issuance, usually for compliance and audit purposes. - ZUGFERD: A hybrid eInvoicing format used in Germany combining PDF and XML for human and machine readability. - CTC: Continuous Transaction Controls involve real-time or near-real-time invoice validation and transmission to tax authorities. - NEMHANDEL: Denmark’s national infrastructure for eInvoicing that supports secure delivery via specific formats like OIOUBL. - FACE: Spain’s centralized system (FACe/FACeB2B) for routing invoices to government or private recipients. - VERIFACTU: Spain’s mechanism for validating and reporting sales invoices directly to the tax agency. enum: - PEPPOL - EINVOICE - CLEARANCE - REPORTING - ZUGFERD - CTC - NEMHANDEL - FACE - VERIFACTU example: PEPPOL type: string document_type: description: Type of business document. example: ubl-invoice type: string fields: description: List of input fields with inclusion metadata. items: $ref: '#/components/schemas/data_input_fields_response_fields_inner' type: array type: object bad_request_error_response: example: errors: - code: MISSING_REQUIRED_DATA message: The request did not contain a required property 'taxAmount' help_url: https://docs.example.com/errors#MISSING_REQUIRED_PARAMETER properties: errors: items: $ref: '#/components/schemas/bad_request_error_response_errors_inner' type: array provider_interaction: $ref: >- #/components/schemas/document_submission_response_provider_interaction type: object 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 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 bad_request_error_response_errors_inner: properties: code: description: >- The error codes classify the type of exception that occurred during processing the request. enum: - INVALID_OPERATION - SERVICE_EXCEPTION - SERVICE_UNAVAILABLE - SERVICE_LIMIT_EXCEEDED - MISSING_REQUIRED_DATA - INVALID_DATA type: string message: description: A short message describing the reason for the error. type: string help_url: description: >- The link to the documentation for more information about the error and the corrective action. format: uri type: string required: - message type: object 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 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 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 securitySchemes: ApiKeyAuth: in: header name: Authorization type: apiKey ````