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_scheme": [
        {
          "scheme": "VAT",
          "id": "DE987654321"
        }
      ]
    },
    "accounting_customer_party": {
      "name": "Example Buyer GmbH",
      "address": {
        "line_1": "Berliner Str. 123",
        "line_2": "2nd Floor",
        "zip": "10115",
        "city": "Berlin",
        "country": "DE"
      },
      "tax_scheme": [
        {
          "scheme": "VAT",
          "id": "DE123456789"
        }
      ]
    },
    "payment_means": [
      {
        "code": "ONLINE_PAYMENT_SERVICE",
        "payment_id": "PAY-2024-00987",
        "card_account": {
          "primary_account_number_id": "4111********1111",
          "card_holder_name": "Jane Smith",
          "network_id": "MASTERCARD"
        }
      }
    ],
    "lines": [
      {
        "id": "1",
        "description": "Consulting Services - April",
        "quantity": 1,
        "unit_price": 100.0,
        "amount": 100.0,
        "item_code": "CONS-APRIL",
        "classified_tax_category": [
          {
            "percentage": 14,
            "category": "VAT",
            "country": "DE"
          }
        ]
      }
    ],
    "tax_total": {
      "tax_amount": 14.0,
      "tax_sub_totals": [
        {
          "taxable_amount": 100.0,
          "tax_amount": 14.0,
          "percentage": 14,
          "country": "DE",
          "category": "VAT"
        }
      ]
    }
  }'

{
  "document_id": "DOC-20250402-0002",
  "status": "ACCEPTED",
  "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

{
  "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"
    }
  ]
}

{
  "message": "An unexpected error occurred while processing your request."
}

Documents

Submit a document

Submits a new document, such as an invoice or credit note, to the connected e-invoicing provider for validation, compliance checks, and delivery to the appropriate tax authorities or business partners.

This endpoint is MANDATORY for enabling document submission through the Chargebee E-invoicing SPI framework.

Within Chargebee, this endpoint is invoked asynchronously by an internal background job whenever a new invoice, credit note, or other supported billing document is generated and requires processing through the configured e-invoicing provider.

If the e-invoicing provider requires merchants to configure field mappings manually, instead of relying on predefined mappings managed by Chargebee, Chargebee will collect this mapping as entered by the Chargebee merchant through the Chargebee Admin Console.

The collected field mapping and the corresponding input values will be passed to the adapter via the overrides parameter.

Note: When the overrides parameter is present, the adapter must rely exclusively on the field_mapping and values defined within it. All other standard schema fields should be ignored for transformation purposes.

Additionally, this endpoint supports submission of Application Response documents, such as invoice acknowledgements or rejections, to facilitate downstream workflows and business rule validation. These responses are submitted using the same endpoint but distinguished using a type discriminator with APPLICATION_RESPONSE.

POST

einvoicing

documents

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_scheme": [
        {
          "scheme": "VAT",
          "id": "DE987654321"
        }
      ]
    },
    "accounting_customer_party": {
      "name": "Example Buyer GmbH",
      "address": {
        "line_1": "Berliner Str. 123",
        "line_2": "2nd Floor",
        "zip": "10115",
        "city": "Berlin",
        "country": "DE"
      },
      "tax_scheme": [
        {
          "scheme": "VAT",
          "id": "DE123456789"
        }
      ]
    },
    "payment_means": [
      {
        "code": "ONLINE_PAYMENT_SERVICE",
        "payment_id": "PAY-2024-00987",
        "card_account": {
          "primary_account_number_id": "4111********1111",
          "card_holder_name": "Jane Smith",
          "network_id": "MASTERCARD"
        }
      }
    ],
    "lines": [
      {
        "id": "1",
        "description": "Consulting Services - April",
        "quantity": 1,
        "unit_price": 100.0,
        "amount": 100.0,
        "item_code": "CONS-APRIL",
        "classified_tax_category": [
          {
            "percentage": 14,
            "category": "VAT",
            "country": "DE"
          }
        ]
      }
    ],
    "tax_total": {
      "tax_amount": 14.0,
      "tax_sub_totals": [
        {
          "taxable_amount": 100.0,
          "tax_amount": 14.0,
          "percentage": 14,
          "country": "DE",
          "category": "VAT"
        }
      ]
    }
  }'

{
  "document_id": "DOC-20250402-0002",
  "status": "ACCEPTED",
  "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

{
  "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"
    }
  ]
}

{
  "message": "An unexpected error occurred while processing your request."
}

Authorizations

Authorization

string

header

required

Body

application/json

Option 1
Option 2

Represents an invoice or credit note document to be validated and submitted via the e-invoicing provider.

string

required

A unique identifier for the document being submitted. This typically represents the invoice number or credit note number generated by Chargebee.

type

enum<string>

required

Type of document, either an invoice or a credit note.

Available options:

INVOICE,

CREDIT_NOTE

country

string

required

The ISO country code for the scenario.

Example:

"DE"

model

enum<string>

required

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.

Available options:

PEPPOL,

EINVOICE,

CLEARANCE,

REPORTING,

ZUGFERD,

CTC,

NEMHANDEL,

FACE,

VERIFACTU

Example:

"PEPPOL"

issue_date

string<date>

required

The date when the document was issued. Format "YYYY-MM-DD"

tax_date

string<date>

required

The date used to determine tax. Format "YYYY-MM-DD"

currency_code

string

required

The currency code ISO 4217 format for the document.

due_date

string<date>

required

The date when the payment is due. Format "YYYY-MM-DD".

amount

number

required

Total payable amount for the document, including taxes.

status

enum<string>

required

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.

Available options:

PAID,

POSTED,

PAYMENT_DUE,

NOT_PAID,

VOIDED,

ADJUSTED,

REFUNDED,

REFUND_DUE

Example:

"PAYMENT_DUE"

taxable_amount

number

required

Total document amount excluding tax (VAT).

amount_due

number

required

Outstanding balance remaining on the document.

accounting_supplier_party

object

required

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.

Show child attributes

accounting_customer_party

object

required

Party responsible for receiving the invoice (i.e., the customer).

Show child attributes

lines

object[]

required

Show child attributes

tax_total

object

required

Represents the total tax details for the document.

Show child attributes

transaction_type

enum<string>

The type of transaction (B2B, B2C, B2G).

Available options:

B2B,

B2C,

B2G

Example:

"B2B"

document_type

string

Type of business document.

Example:

"ubl-invoice"

total_discount

number

Sum of all discounts applied across line items on the document.

note

string

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.

billing_reference

object[]

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.

Show child attributes

payment_means

object[]

A list of payment methods with corresponding payment details.

Show child attributes

overrides

object

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:
```
{
  "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:
```
{
  "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.

Show child attributes

Response

Document submitted successfully.

document_id

string

required

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.

status

enum<string>

required

The current status of the submitted document.

Available options:

ACCEPTED,

FAILED,

SUCCESS

request_id

string

A unique identifier assigned to the request for tracking and correlation purposes across systems and logs.

provider_interaction

object

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.

Show child attributes

Example:

{
  "request": { "body": "{}" },
  "response": { "status_code": 0, "body": "{}" }
}

Retrieves data input fields Get Document Status

⌘I