API Docs

Disclosed agent billing

Use this payload for disclosed agent billing purchase invoice scenarios.

Contract reference

Core fields

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

Root-level fields used in this example.

Field	Type	Required	Description	Validation
`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.	For purchase invoices created via API, this must be `389` (Self-billed Invoice).
`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 section for details.
`accounting_customer_party`	object	Required	The customer party for the invoice. See Party object below.	Must be a valid Party object; required in create requests.
`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`.
`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.
`payment_means`	array	Optional	Payment method. See Payment means array below.	Optional. May be omitted or `null`. When provided, certain codes require card, account, or mandate details.
`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.

Party object

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

Field requirements depend on whether the party is the buyer or seller. See The Customer party object and The Supplier party object.

Field	Type	Required	Description	Validation
`name`	string	Required	Party name or display name.	Must be non-empty text.
`party_name`	string	Conditional	Legal name of the party.	Required for business parties. Do not send for individual customers.
`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 section for details.	Required; must satisfy address object validation.
`scheme_agency_id`	string	Optional	Registration type identifier, if you choose to include registration details.	Optional for customer and supplier parties. If sent, must match allowed values for the party type — see The Customer party object or The Supplier party object. See Get Registration Types section for details.
`company_id`	string	Optional	Registration or identity number when registration details are included.	Optional. Distinct from VAT TRN in `party_tax_scheme.company_id`. Required only when `scheme_agency_id` is provided.
`authority_name`	string	Optional	Issuing authority for the trade license.	Optional. Required only when `scheme_agency_id` is `TL` and registration details are included.
`passport_issuing_country_code`	string	Optional	Country that issued the passport.	Optional. Required only when `scheme_agency_id` is `PAS` and registration details are included.
`tin`	string	Conditional	Taxpayer Identification Number (TIN).	Required for UAE business customers and UAE suppliers. Exactly 10 characters, must start with `1`. Do not send for non-UAE B2B parties.
`party_tax_scheme`	object	Optional	Tax scheme with UAE VAT/TRN. Contains `company_id`, `tax_scheme`.	Optional for UAE parties. If either `company_id` or `tax_scheme` is provided, both are required. When `company_id` is set: 15 numeric characters, 15 digits; starts with `1` and ends with `03`. Optional for non-UAE `accounting_customer_party` on export transactions (`profile_execution_id` seventh character is `1`). Forbidden for non-UAE B2B parties. See Get Tax Schemes and The Supplier party object.
`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. Typically `0235` for UAE.	If present, must be a valid Peppol scheme id. See Get Electronic Address Schemes section for details.
`email`	string	Required	Party email address.	Required for customer and supplier parties.
`telephone`	string	Conditional	Party telephone number.	Required for UAE suppliers. Optional for customers.

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 section for details.

Price object

The price object on each document_lines[] entry carries the item net price and price base quantity.

Field	Type	Required	Description	Validation
`base_amount`	number	Required	Item net price (ibt-146).	Must not be negative.
`base_quantity`	number	Required	Item price base quantity (ibt-149).	Must be a positive number above zero. Must use the same unit code as `document_lines[].unit_code` (ibt-150).
`allowance`	object	Optional	Price-level allowance (discount on the item net price).	If present, see price allowance below.
`allowance.amount`	number	Optional	Price-level discount amount.	Must not be negative when provided.

Tax category object

Tax categories share the same structure on line items (classified_tax_category) and charge/allowance tax_category fields. classified_tax_category is required on each line. Document-level charge and allowance tax categories are required; line-level charge and allowance tax categories are optional.

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 section for details.
`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 section for details.
`tax_exemption_reason`	string	Conditional	Tax exemption reason description.	Required when `id` is `E` (exempt). Must match the selected `tax_exemption_reason_code` description.
`tax_scheme`	string	Optional	Tax scheme identifier (typically `VAT` for UAE).	See Get Tax Schemes section for details.

Document line object

Each element of the document_lines array represents one invoice line (UBL InvoiceLine). Nested item fields map to the UBL Item group. For Item Type, HSN, and SAC mappings from your ERP or Marmin UI, see Line item classification (UI to API).

Field	Type	Required	Description	Validation
`name`	string	Required	Item name (ibt-153): a name for the item.	Must be non-empty.
`description`	string	Required	Item description (ibt-154): a description for the item.	Must be non-empty.
`quantity`	number	Required	Invoiced quantity (ibt-129).	Must be a positive number.
`unit_code`	string	Required	Invoiced quantity unit of measure code (ibt-130).	Must be a valid UN/ECE Rec 20/21 code (e.g. `EA`, `KGM`, `LTR`). See Get Unit of Measure Codes section for details.
`price`	object	Required	Item net price details. See Price object section for details.	Must satisfy Price object validation.
`classified_tax_category`	object	Required	Line VAT information: VAT applicable for the goods and services invoiced on this line. See Tax category object section for details.	Must satisfy Tax category object validation; `tax_exemption_reason_code` and `tax_exemption_reason` are required when `id` is `E`.
`note`	string	Optional	Free-text note for the line.	Free text.
`accounting_cost`	string	Optional	Accounting cost center for this line.	Free text.
`invoice_period`	object	Optional	Line invoicing period (ibt-134, ibt-135). See Invoice period object section for details.	If present: dates in `yyyy-MM-dd`, with `start_date` ≤ `end_date`; line period must fall within document-level `invoice_period` when both are sent.
`order_line_reference`	object	Optional	Invoice line identifier (ibt-126). See Order line reference object section for details.	Required for compliance (`IBR-021`): must include `line_id` when sent.
`despatch_line_reference`	object	Optional	Reference to a despatch document line. See Despatch line reference object section for details.	If present, must be valid.
`document_reference`	object	Optional	Reference to a related document for this line. See Line document reference object section for details.	If present: `id` required.
`charges`	array	Optional	Line-level charges that increase the line amount. See Charge object section for details.	If present: each item must include `reason` or `reason_code`. `tax_category` is optional at line level.
`allowances`	array	Optional	Line-level allowances (discounts) on the line. See Allowance object section for details.	If present: each item must include `reason` or `reason_code`. `tax_category` is optional at line level.
`buyer_item_identification`	object	Optional	Buyer's item identification: an identifier assigned by the buyer for the item. See Buyer item identification object section for details.	If present: must include `id`.
`seller_item_identification`	object	Optional	Seller's item identification: an identifier assigned by the seller for the item. See Seller item identification object section for details.	If present: must include `id`.
`standard_item_identification`	object	Optional	Standard item identification (ibt-157): an item identifier based on a registered scheme. See Standard item identification object section for details.	If present: must include `id` and `scheme_id` (`IBR-064`).
`additional_item_identification`	array	Conditional	Service Accounting Code (SAC) for service lines. Required when Item Type is Services (`S`) or Both (`B`). See Additional item identification object and Line item classification (UI to API).	When required: include at least one entry with `id` (SAC value) and `scheme_id`: `"SAC"` (`IBR-189-AE`).
`origin_country`	object	Optional	Origin country: country of origin for the item. See Origin country object section for details.	If present: must include a valid country identification code.
`commodity_classification`	object	Conditional	Item type, HSN, and reverse-charge metadata for the line. Maps UI Item Type and Item Classification Identifier fields. See Commodity classification object and Line item classification (UI to API).	When Item Type is Goods (`G`) or Both (`B`): require `commodity_code`, `item_classification_code`, and `item_classification_list_id`: `"HS"`. When Services only (`S`): send `commodity_code`; use `additional_item_identification` for SAC.
`additional_item_property`	array	Optional	Item attributes: properties of the goods and services invoiced on this line. See Additional item property object section for details.	If present: each item must include `name` and `value`.
`lot_number_id`	string	Optional	Batch number: an identifier for the production batch or lot that the items come from.	Free text.
`line_object_identifier`	string	Optional	Internal line object identifier used by your integration.	Free text.
`base_amount`	number	—	Extended quantity × unit price before tax, charges, and allowances.	Response-only; do not send on create.
`net_amount`	number	—	Invoice line net amount (ibt-131).	Response-only; do not send on create.
`total_amount`	number	—	Line total including tax.	Response-only; do not send on create.
`tax_amount`	number	—	VAT amount for this line.	Response-only; do not send on create.
`total_amount_in_aed`	number	—	Line total in AED when document currency differs.	Response-only; do not send on create.
`tax_amount_in_aed`	number	—	Line tax amount in AED when document currency differs.	Response-only; do not send on create.

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).	Required when a `payment_means` item is sent. Must not be blank. Must be one of: `1`, `10`, `20`, `21`, `30`, `49`, `54`, `55`, `68`. See Get Payment Means Modes section for details.
`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`.

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`).

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 purchase invoice with no special types.

payment_means is optional and may be omitted or null.

Transaction scenarios follow PINT AE. Set the corresponding position to 1 when the supply matches that scenario; leave it 0 otherwise. Multiple flags may be 1 when more than one scenario applies.

Ready-to-use payloads for each scenario are on the purchase invoice Examples page.

Transaction type	Position	When to use	When the flag is `1`
Free trade zone	1XXXXXXX	Supply of goods or services in a free trade zone.	Set `buyer_customer_party.id` (Beneficiary TIN). See Buyer customer party object section for details. Example payload: Free Trade Zone.
Deemed supply	X1XXXXXX	Supply of goods or services without consideration.	No additional mandatory fields beyond standard validation.
Profit Margin Scheme	XX1XXXXX	Supply of goods under the profit margin scheme.	No additional mandatory fields beyond standard validation.
Summary invoice	XXX1XXXX	Taxable person makes more than one supply of goods or services to the same person in the same calendar month.	Set `invoice_period.start_date`, `invoice_period.end_date`, and `invoice_period.description`. Example payload: Summary invoice.
Continuous Supply	XXXX1XXX	Supply of goods and/or services made on a recurrent basis.	No additional mandatory fields beyond standard validation.
Agent billing	XXXXX1XX	Agent who is a registrant makes a supply on behalf of the principal.	Set `seller_supplier_party.id` (Principle ID TRN) for disclosed agent billing payloads. See Seller supplier party object section for details. Example payload: Disclosed agent billing.
Supply through e-commerce	XXXXXX1X	Supply of goods or services via e-commerce.	Include `delivery` with `delivery_location.address` when required by your business scenario. See Delivery object section for details.
Exports	XXXXXXX1	Supply of goods or services outside the country.	Include `delivery` with `delivery_location.address`. `accounting_customer_party.party_tax_scheme` is optional when the buyer is non-UAE. See Delivery object section for details. Example payload: Export transaction with delivery.

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

Scenario	Typical `profile_execution_id`	Examples page
Standard invoice (baseline)	`00000000`	Minimal purchase invoice
Free Trade Zone	`10000000`	Free Trade Zone
Summary invoice	`XXX1XXXX` (flag in position 4)	Summary invoice
Disclosed agent billing	`XXXXX1XX` (flag in position 6)	Disclosed agent billing
Export delivery	`XXXXXXX1`	Export transaction with delivery

See the example payload in the right-side panel.