Data models

Data Formats, Precision, and Validation

Failure to adhere to the defined standards will result in data processing errors, which can lead to unexpected behavior or request rejection.

Data Encoding

All data must be UTF-8 encoded to support international characters and ensure compatibility.

Example: "name": "José Álvarez" (properly handles accented characters in UTF-8).

Date and Time Formatting

ISO 8601 format is used for all dates unless otherwise specified. All dates are in UTC.

Example: 2020-06-25T08:31:24.379Z (ISO 8601, UTC timestamp).

Currency codes

ISO 4217-1 alpha-3 is used for all currency codes.

Example: USD (two decimal places, USD currency code).

Country codes

ISO 3166-1 alpha-3 is used for all country codes.

Example: JPN (Japan).

Precision and Rounding Rules

Numeric fields support up to four decimal places, rounded to two for display, validation, and calculations.

Example: 12.3456 (four decimal places) rounded to 12.35 (two decimal places).

eezi's API supports more than two decimal places for invoice fields, ensuring accurate totals, taxes, and discounts—critical for high-volume transactions and compliance with industry regulations. However, some tax reporting formats may require only two decimal places. Therefore, eezi automatically rounds totals and tax amounts as needed for validation and as required by destination formats.

When rounding invoice totals and calculations, we use symmetric rounding (also known as "round away from zero"). This means both positive and negative numbers round in the same direction relative to zero.

Examples:

• Positive: 120.375 rounds up to 120.38 (away from zero)
• Negative: -120.375 rounds down to -120.38 (away from zero)

Note: The negative value rounds to -120.38, NOT -120.37. Standard rounding rules would round -120.375 toward zero (to -120.37), but symmetric rounding rounds away from zero (to -120.38).

Document Lifecycle

When a document (invoice or credit note) is submitted via the API, it progresses through the following statuses:

• pending submission — The document has been accepted by eezi and is being processed or awaiting a response from the downstream tax authority.
• pending response — The document was submitted to the tax authority, but a final response has not yet been received. This typically occurs with authorities that process submissions asynchronously.
• success — The document was successfully submitted and accepted by the tax authority.
• error — The submission failed. The error object on the document contains the details (name, message, description).

In some cases, the API returns a 202 Accepted response when downstream systems are slow. Use the read endpoint to poll for the final status. For more details on handling timeouts and async responses, see Common Errors.

Invoices

We support invoices for various countries. Read more on the generic eezi invoice model, which covers the base invoice fields and the supported invoice variants here.

Credit Notes

We support credit notes for various countries. Read more on the generic eezi credit note model, which covers the base credit note fields and supported variants here.