> ## 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. # Receive document status updates for an invoice > 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. ## OpenAPI ````yaml post /api/v2/invoices/{document_id}/einvoice_status 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: /api/v2/invoices/{document_id}/einvoice_status: post: tags: - Callbacks summary: Receive document status updates for an invoice 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 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"}}' components: schemas: 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 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 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 securitySchemes: ApiKeyAuth: in: header name: 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 ````