API Docs

The proforma invoice object

See the right panel for the complete object definition and code examples.

Attributes

Core fields

All root-level attributes on the proforma invoice. Nested fields are linked to their respective tables below for full attribute details.

Field	Type	Required	Description	Validation
`id`	string	Required	Primary identifier for the document (UUID). Automatically generated when the invoice is created.	Response-only; not accepted in requests.
`org_id`	string	Required	Unique identifier of the organization that owns this invoice.	Set by backend from your organization; not part of the create request body.
`document_number`	string	Optional	The invoice number as displayed on the document. If not provided and auto-numbering is enabled, the system will generate this automatically.	Required for API-created invoices; must be unique within the organization when provided.
`document_sequence`	long	Optional	Sequential number for the invoice within your organization. Used for compliance and tracking.	Server-calculated sequence; do not send on create.
`issue_date`	string	Required	The date when the invoice was issued.	Format `yyyy-MM-dd`; must be a valid calendar date.
`issue_time`	string	Optional	The time when the invoice was issued.	If present, format `HH:mm:ss` (e.g. `10:30:00`).
`invoice_type_code`	string	Required	The type of invoice.	Must be one of `380`, `389`, `480`; Proforma Invoice API typically forces `380`.
`due_date`	string	Required	The date when payment is due.	Format `yyyy-MM-dd`.
`profile_execution_id`	string	Required	Invoice transaction type code. See Profile execution ID below.	Exactly 8 characters; each character `0` or `1` (binary flags).
`document_currency_code`	string	Required	ISO 4217 alpha-3 currency code for all monetary amounts (e.g. `AED`).	Must be a valid ISO 4217 currency (e.g. `AED`). See Get Currency Names and Codes.
`tax_currency_code`	string	Optional	ISO 4217 currency code for tax when it differs from document currency.	If present: valid ISO 4217 code; consistent with `document_currency_code` and requires `tax_exchange_rate` when different. See Get Currency Names and Codes.
`accounting_cost`	string	Optional	Accounting cost center / project cost identifier (if applicable).	Free text.
`buyer_reference`	string	Optional	Buyer reference (customer reference) for the invoice.	Free text.
`invoice_period`	object	Optional	Billing period covered by the invoice (start_date, end_date, description).	If present: `start_date` and `end_date` must be `yyyy-MM-dd`, with `start_date` ≤ `end_date`.
`note`	string	Optional	Additional notes or terms displayed on the invoice.	Free text.
`tax_point_date`	string	Optional	Tax point date per UAE VAT Law—when VAT liability arises.	If present: format `yyyy-MM-dd`; defaults to `issue_date` if omitted.
`accounting_supplier_party`	object	Required	The supplier party issuing the invoice. See Party object below.	For Sales Invoice API, usually derived from the supplier profile; if sent, must be a valid Party.
`accounting_customer_party`	object	Required	The customer party receiving the invoice. See Party object below.	Must be a valid Party object; required in create requests.
`buyer_customer_party`	object	Optional	UAE e-invoicing field for Beneficiary ID (UBL `BTAE-01`). This is not a full party object. See Buyer customer party object below.	Required when Free Trade Zone applies (`profile_execution_id` first character is `1`); `id` must be a valid Beneficiary ID (TIN).
`seller_supplier_party`	object	Optional	UAE e-invoicing field for Principle ID (UBL `BTAE-14`). This is not a full party object. See Seller supplier party object below.	Required when Disclosed Agent Billing applies (`profile_execution_id` sixth character is `1`); `id` must be a valid Principle ID TRN and must differ from `accounting_supplier_party.party_tax_scheme.company_id`.
`payee_party`	object	Optional	The party to whom payment should be made, if different from the supplier. See Payee party object below.	If present, must be a valid Payee party object.
`tax_representative_party`	object	Optional	Party authorized to represent the supplier for tax purposes. See Tax representative party object below.	If present, must be a valid Party (with correct tax scheme and address).
`delivery`	object	Optional	Delivery details: location (and address), optional actual delivery date, party, and terms. See Delivery object below.	If present: `delivery_location` is required and must include `address`. Mandatory when the export transaction type applies (`profile_execution_id`).
`order_reference`	object	Optional	Reference to the purchase order. See Order reference object below.	If present: `id` must be provided; `issue_date` as `yyyy-MM-dd` when used.
`billing_reference`	array	Optional	References to other billing documents (e.g. previous invoices, credit notes). See Billing reference object below.	If present: each item requires `id`; `issue_date` as `yyyy-MM-dd` when provided.
`despatch_document_reference`	object	Optional	Reference to despatch/delivery document. See Despatch document reference object below.	If present: `id` required; `issue_date` `yyyy-MM-dd` when provided.
`receipt_document_reference`	object	Optional	Reference to receipt document. See Receipt document reference object below.	If present: `id` required; `issue_date` `yyyy-MM-dd` when provided.
`statement_document_reference`	object	Optional	Reference to statement document.	If present: `id` required; `issue_date` `yyyy-MM-dd` when provided.
`originator_document_reference`	object	Optional	Reference to originating document (when applicable).	If present: `id` required; `issue_date` `yyyy-MM-dd` when provided.
`contract_document_reference`	object	Optional	Reference to contract. See Contract document reference object below.	If present: `id` required; `issue_date` `yyyy-MM-dd` when provided.
`project_reference`	object	Optional	Project associated with the invoice. See Project reference object below.	If present: `id` must be provided.
`document_lines`	array	Required	Invoice line items. See Document line object below.	Must contain at least one line; each line must satisfy the Document line object validation rules.
`charges`	array	Optional	Document-level charges that increase the amount. See Charge object below.	If present: each charge must have a valid reason and amount/rate; tax category rules apply.
`allowances`	array	Optional	Document-level discounts/allowances. See Allowance object below.	If present: each allowance must have a valid reason and amount/rate; tax category rules apply.
`payment_means`	array	Optional	Payment method. See Payment means array below.	Required when `profile_execution_id` first bit is `0`; optional when first bit is `1`. Certain codes require card or mandate details.
`payment_terms`	object	Optional	Payment terms and conditions. See Payment terms object below.	Free structure with date fields in `yyyy-MM-dd` when used.
`tax_exchange_rate`	object	Optional	Exchange rate when tax currency differs from document currency. See Tax exchange rate object below.	Required when `tax_currency_code` differs from `document_currency_code`; must include `source_currency_code`, `target_currency_code`, and `calculation_rate`.
`prepaid_amount`	number	—	Total prepaid amount applied to the invoice.	Optional numeric; typically non-negative.
`payable_rounding_amount`	number	—	Rounding adjustment applied to payable amount.	Optional numeric; may be positive or negative depending on rounding direction.
`allowance_total_amount`	number	—	Total of all document-level allowances.	Response-only, calculated from document-level allowances.
`charge_total_amount`	number	—	Total of all document-level charges.	Response-only, calculated from document-level charges.
`line_extension_amount`	number	—	Sum of all line amounts before charges, allowances, and taxes. UBL 2.1 LineExtensionAmount.	Response-only, derived from line net amounts.
`tax_exclusive_amount`	number	—	Line extension plus charges minus allowances, before tax. UBL 2.1 TaxExclusiveAmount.	Response-only, calculated.
`tax_amount`	number	—	Aggregated VAT amount in document currency. UBL 2.1 TaxTotal.	Response-only, calculated from tax breakdown.
`tax_amount_in_aed`	number	—	Total tax amount converted to AED.	Response-only, calculated using tax exchange rate (if applicable).
`tax_inclusive_amount`	number	—	Tax exclusive amount plus total tax. UBL 2.1 TaxInclusiveAmount.	Response-only, calculated.
`payable_amount`	number	—	Final amount due. UBL 2.1 PayableAmount.	Response-only, calculated as tax inclusive minus prepayments/rounding.
`payable_amount_in_aed`	number	—	Final amount payable in AED.	Response-only, calculated using exchange rates.
`total_item_allowances`	number	—	Total of all line-level allowances.	Response-only, sum over line-level allowances.
`total_item_charges`	number	—	Total of all line-level charges.	Response-only, sum over line-level charges.
`total_taxable_amount`	number	—	Total taxable amount.	Response-only, derived from taxable lines and charges/allowances.
`total_non_taxable_amount`	number	—	Total non-taxable amount.	Response-only, derived from non-taxable lines.
`tax_breakdown`	array	—	Tax amounts by tax category (S, Z, E, O, AE, N) and rate. UBL 2.1 TaxSubtotal.	Response-only, generated from per-line tax categories.
`document_source`	string	—	Indicates the origin of the e-invoice document. This identifies the specific external system, ERP, or platform that generated or transmitted the record. Examples: `SAP_S4HANA`, `Oracle_NetSuite`, `Internal_Portal`.	Optional. Accepts a string value. If not provided, the system assigns `API` as the default source.
`is_phase2_document`	boolean	—	Whether the document is Peppol-enabled (Phase 2).	Response-only flag; controlled by backend/Peppol integration.
`meta_info`	object	Optional	Additional metadata. See Meta info object below.	Response-only metadata (timestamps, Peppol status, etc.).

Party object

The accounting_supplier_party and accounting_customer_party fields are full party objects with the following attributes:

Field	Type	Required	Description	Validation
`name`	string	Required	Party name or display name.	Must be non-empty text.
`party_name`	string	Required	Legal name of the party.	Must be non-empty text.
`profile_id`	string	Optional	Business profile identifier when referencing a registered profile.	If provided, must match an existing business profile.
`postal_address`	object	Required	Postal address. See Address object.	Required; must satisfy address object validation.
`scheme_agency_id`	string	Optional	Scheme agency identifier.	If present, must be one of `TL`, `EID`, `PAS`, `CD`, `OTH`. See Get Registration Types.
`company_id`	string	Optional	Company or registration number.	Free-form registration number; may be validated per jurisdiction.
`party_tax_scheme`	object	Conditional	Tax scheme with TRN. Contains `company_id`, `tax_scheme`.	Required for UAE parties (`postal_address.country_code` is `AE`). Optional for non-UAE `accounting_customer_party` on export transactions (`profile_execution_id` seventh character is `1`). If present, must include a valid TRN or tax identifier and `tax_scheme` (usually `VAT`). See Get Tax Schemes.
`endpoint_id`	string	Optional	Peppol endpoint identifier.	If present, must be a valid Peppol endpoint for Phase 2 documents.
`endpoint_scheme_id`	string	Optional	Peppol endpoint scheme identifier.	If present, must be a valid Peppol scheme id. See Get Electronic Address Schemes.
`email`	string	Optional	Party email address.	Free text when provided.
`telephone`	string	Optional	Party telephone number.	Free text when provided.

Address object

Postal and delivery addresses use the shared address object structure.

Field	Type	Required	Description	Validation
`street_name`	string	Required	Street name or primary address line (UBL address line 1).	Must not be blank.
`additional_street_name`	string	Optional	Additional street name or address line 2.	Free text when provided.
`city_name`	string	Required	City or town name.	Must not be blank.
`postal_zone`	string	Optional	Postal or ZIP code.	Free text when provided.
`country_subentity`	string	Required	Country subdivision—emirate, state, or region code.	Must not be blank. When `country_code` is `AE`, use an approved emirate code from Get UAE Subdivisions.
`address_line`	string	Optional	Additional unstructured address line.	Free text when provided.
`country`	string	Required	Country name (e.g. `United Arab Emirates`).	Must not be blank.
`country_code`	string	Required	ISO 3166-1 alpha-2 country code (e.g. `AE`).	Must not be blank. See Get Countries.

Tax category object

Tax categories share the same structure on line items (classified_tax_category), document-level charges[].tax_category, and allowances[].tax_category.

Field	Type	Required	Description	Validation
`id`	string	Required	Tax category code (UBL classified tax category ID).	Must not be blank. Valid codes include `S`, `Z`, `E`, `O`, `AE`, `N`. See Get Tax Categories.
`percent`	number	Optional	VAT rate as a percentage (e.g. `5` for 5%).	Should align with the selected `id`.
`tax_exemption_reason_code`	string	Conditional	FTA tax exemption reason code.	Required when `id` is `E` (exempt). See Get Tax Exemption Reason Codes.
`tax_exemption_reason`	string	Optional	Tax exemption reason description.	Free text when provided; often used with `tax_exemption_reason_code`.
`tax_scheme`	string	Optional	Tax scheme identifier (typically `VAT` for UAE).	See Get Tax Schemes.

Buyer customer party object

The buyer_customer_party field carries the Beneficiary ID (UBL BTAE-01). It is not a full party reference—only the beneficiary identifier is sent in the API.

Field	Type	Required	Description	Validation
`id`	string	Conditional	Beneficiary ID (TIN). Mapped to `BTAE-01` in the generated XML.	Required when Free Trade Zone applies (`profile_execution_id` first character is `1`). Must be a valid TIN; do not use `accounting_customer_party` TRN here.

Seller supplier party object

The seller_supplier_party field carries the Principle ID (UBL BTAE-14). It is not a full party reference—only the Principle ID TRN is sent in the API.

Field	Type	Required	Description	Validation
`id`	string	Conditional	Principle ID TRN. Mapped to `BTAE-14` in the generated XML.	Required when Disclosed Agent Billing applies (`profile_execution_id` sixth character is `1`). Must be a valid TRN; must differ from the seller VAT identifier (`accounting_supplier_party.party_tax_scheme.company_id`).

Payee party object

The payee_party field is an object with the following attributes:

Field	Type	Required	Description	Validation
`party_identification`	object	Optional	Payee identification.	Optional; structure depends on your implementation.
`party_name`	string	Optional	Name of the payee.	If provided, must be non-empty text.
`financial_account`	object	Optional	Financial account details for payment.	If present, must contain valid account identifiers as required by your bank.

Tax representative party object

The tax_representative_party field is an object with the following attributes:

Field	Type	Required	Description	Validation
`party_identification`	object	Optional	Tax representative identification.	Optional; should uniquely identify the tax representative where used.
`party_name`	string	Optional	Name of the tax representative.	If provided, must be non-empty.
`postal_address`	object	Optional	Address of the tax representative.	If present, see Address object.

Delivery object

The delivery field is an object with the following attributes. JSON property names use snake_case as shown.

Field	Type	Required	Description	Validation
`actual_delivery_date`	string	Optional	Actual date of delivery.	If present, format `yyyy-MM-dd`.
`delivery_location`	object	Required when `delivery` is sent	Where goods or services are delivered. See Delivery location object below.	Must be present whenever the `delivery` object is included.
`party_name`	string	Optional	Name of the delivery-related party.	Free text when provided.
`party_id`	string	Optional	Identifier of the delivery-related party.	Free text when provided.
`terms`	string	Optional	Delivery terms.	Free text when provided.

Delivery location object

The delivery_location object has the following attributes.

Field	Type	Required	Description	Validation
`id`	string	Optional	Delivery location identifier.	Free text when provided.
`address`	object	Required	Postal address of the delivery location.	Required when `delivery_location` is present. See Address object.

Order reference object

The order_reference field is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Required	Order number or identifier.	Must be non-empty when the object is present.
`issue_date`	string	Optional	Order date.	If present, format `yyyy-MM-dd`.
`sales_order_id`	string	Optional	Sales order identifier.	Free-form identifier.

Billing reference object

Each element of the billing_reference array is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Required	Referenced document number.	Must be non-empty when the entry is present.
`issue_date`	string	Optional	Referenced document date.	If present, format `yyyy-MM-dd`.

Despatch document reference object

The despatch_document_reference field is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Required	Despatch document number.	Must be non-empty when the object is present.
`issue_date`	string	Optional	Despatch document date.	If present, format `yyyy-MM-dd`.

Receipt document reference object

The receipt_document_reference field is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Required	Receipt document number.	Must be non-empty when the object is present.
`issue_date`	string	Optional	Receipt document date.	If present, format `yyyy-MM-dd`.

Statement document reference object

The statement_document_reference field is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Required	Statement document number.	Must be non-empty when the object is present.
`issue_date`	string	Optional	Statement document date.	If present, format `yyyy-MM-dd`.

Originator document reference object

The originator_document_reference field is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Required	Originating document number or identifier.	Must be non-empty when the object is present.
`issue_date`	string	Optional	Originating document date.	If present, format `yyyy-MM-dd`.

Contract document reference object

The contract_document_reference field is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Required	Contract number or identifier.	Must be non-empty when the object is present.
`issue_date`	string	Optional	Contract date.	If present, format `yyyy-MM-dd`.

Project reference object

The project_reference field is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Required	Project identifier.	Must be non-empty when the object is present.
`name`	string	Optional	Project name.	Free text.

Document line object

Each element of the document_lines array is an object with the following attributes:

Field	Type	Required	Description	Validation
`name`	string	Required	Line item name.	Must be non-empty.
`description`	string	Optional	Line item description.	Free text.
`unit_code`	object	Required	Unit of measure. Contains `code` (e.g. `EA`), `desc`.	Must contain a valid UN/CEFACT unit code (e.g. `EA`, `KGM`, `LTR`). See Get Unit of Measure Codes.
`quantity`	number	Required	Quantity.	Must be a positive number.
`price`	object	Required	Price. Contains `base_amount`, `base_quantity`.	Must include `base_amount`; `base_quantity` should be positive when provided.
`base_amount`	number	Optional	Calculated base amount.	Response-only; calculated as quantity × price.
`net_amount`	number	Optional	Net amount.	Response-only; calculated.
`total_amount`	number	Optional	Total including tax.	Response-only; calculated.
`tax_amount`	number	Optional	Tax amount for the line.	Response-only; calculated from line tax.
`classified_tax_category`	object	Required	Line-item tax category. See Tax category object.	Must satisfy Tax category object validation; `tax_exemption_reason_code` is required when `id` is `E`.

Charge object

Each element of the charges array is an object with the following attributes:

Field	Type	Required	Description	Validation
`charge_reason_code`	string	Required	UN/ECE Recommendation 20 charge reason code.	Must be a valid UN/ECE charge reason code (e.g. `FC`). See Get Charge Reason Codes.
`amount`	number	Required	Charge amount.	Must be numeric, usually ≥ 0.
`base_amount`	number	Optional	Base amount for the charge.	If used with percentages, must be provided consistently with multiplier/factor logic in your profile.
`tax_category`	object	Optional	Tax category applied to the charge.	If present, see Tax category object. `tax_exemption_reason_code` required when `id` is `E`.

Allowance object

Each element of the allowances array is an object with the following attributes:

Field	Type	Required	Description	Validation
`reason`	string	Conditional	Free-text allowance reason.	At least one of `reason` or `reason_code` must be provided. Free text when provided.
`reason_code`	string	Conditional	UN/ECE Recommendation 20 allowance reason code.	At least one of `reason` or `reason_code` must be provided. Must be a valid code (e.g. `95`). See Get Discount Reason Codes.
`amount`	number	Required	Allowance amount.	Must be numeric, usually ≥ 0.
`base_amount`	number	Optional	Base amount for the allowance.	If used with percentages, must be provided consistently with multiplier/factor logic in your profile.
`tax_category`	object	Optional	Tax category for allowance adjustment.	If present, see Tax category object. `tax_exemption_reason_code` required when `id` is `E`.

Payment means array

The payment_means field is an array; each element is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Optional	Payment means identifier.	Optional identifier for the payment instruction.
`payment_means_code`	string	Required	Payment means code (e.g. `54` for credit card).	Must not be blank. Must be one of: `1`, `10`, `20`, `21`, `30`, `49`, `54`, `55`, `68`. See Get Payment Means Modes.
`payment_id`	array of strings	Optional	Payment reference identifiers.	Used for payment reconciliation.
`card_account`	object	Conditional	Card account details.	Mandatory when `payment_means_code` is `54` or `55`.
`payee_financial_account`	object	Conditional	Payee bank/financial account details.	Mandatory when `payment_means_code` is `30`.
`payment_mandate`	object	Conditional	Payment mandate details.	Mandatory when `payment_means_code` is `49`.

Card account object

The card_account field is an object with the following attributes:

Field	Type	Required	Description	Validation
`primary_account_number_id`	string	Required	Primary account number identifier. UI label: PAN.	Mandatory when `payment_means_code` is `54` or `55`; must not be blank.
`network_id`	string	Required	Card network identifier. UI label: Network ID.	Mandatory when `payment_means_code` is `54` or `55`; must not be blank.
`holder_name`	string	Optional	Card holder name.	Free text.

Payee financial account object

The payee_financial_account field is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Optional	Payee financial account identifier. UI label: Payment account identifier.	Mandatory when `payment_means_code` is `30`.
`name`	string	Optional	Payee financial account name.	Free text.
`financial_institution_branch_id`	string	Optional	Financial institution branch identifier.	Free text.
`address`	object	Optional	Payee financial account address.	If present, see Address object.

Payment mandate object

The payment_mandate field is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Optional	Payment mandate identifier. UI label: Mandate reference Identifier.	Mandatory when `payment_means_code` is `49`.
`payer_financial_account_id`	string	Optional	Payer financial account identifier. UI label: Payer Financial Account Identifier.	Mandatory when `payment_means_code` is `49`.

Payment terms object

The payment_terms field is an object with the following attributes:

Field	Type	Required	Description	Validation
`note`	string	Optional	Payment terms description.	Free text.
`due_date`	string	Optional	Payment due date.	If present, format `yyyy-MM-dd`.
`installment_due_date`	string	Optional	Installment due date.	If present, format `yyyy-MM-dd`.
`amount`	number	Optional	Amount due.	Must be numeric if provided.

Tax exchange rate object

The tax_exchange_rate field is an object with the following attributes:

Field	Type	Required	Description	Validation
`source_currency_code`	string	Required	Source currency (ISO 4217).	Must be a valid ISO 4217 code. See Get Currency Names and Codes.
`target_currency_code`	string	Required	Target currency (ISO 4217).	Must be a valid ISO 4217 code and usually match `tax_currency_code`. See Get Currency Names and Codes.
`calculation_rate`	number	Required	Exchange rate for tax calculation.	Must be a positive numeric rate.

Meta info object

The meta_info field is an object with the following attributes:

Field	Type	Required	Description	Validation
`created_at`	string	Optional	Creation timestamp.	Response-only; ISO 8601 timestamp.
`updated_at`	string	Optional	Last modified timestamp.	Response-only; ISO 8601 timestamp.
`peppol_status`	object	Optional	Peppol transmission status and log.	Response-only; structure defined by Peppol integration.

Profile execution ID

profile_execution_id is an 8-character binary flag string (each character 0 or 1) that encodes UAE special transaction types. Use 00000000 for a standard proforma with no special types.

Flag order and field rules match sale invoice Profile execution ID. For ready-to-use payloads by scenario, see Sale invoice Examples (Examples 5–8).

Transaction type	Position	When the flag is `1`
Free Trade Zone	1XXXXXXX	`payment_means` is optional when this flag is `1`; required when position 1 is `0`.
Deemed Supply	X1XXXXXX	No additional mandatory fields beyond standard validation.
Profit Margin Scheme	XX1XXXXX	No additional mandatory fields beyond standard validation.
Summary Invoice	XXX1XXXX	No additional mandatory fields beyond standard validation.
Continuous Supply	XXXX1XXX	No additional mandatory fields beyond standard validation.
Disclosed Agent Billing	XXXXX1XX	Set `seller_supplier_party.id` (Principle ID TRN). See Seller supplier party object. Example payload: Example 7: Disclosed agent billing.
Supply through e-commerce	XXXXXX1X	No additional mandatory fields beyond standard validation.
Exports	XXXXXXX1	Include `delivery` with `delivery_location.address`. `accounting_customer_party.party_tax_scheme` is optional when the buyer is non-UAE. See Delivery object. Example payload: Example 8: Export transaction.

*Each position X is 0 or 1 depending on your scenario.*

Payment means: If position 1 is 0, you must provide payment_means. If position 1 is 1, payment_means is optional.

Scenario	Examples page
Free Trade Zone, summary invoice, disclosed agent, export	Sale invoice Examples