MarminDeveloper Docs
The purchase invoice object

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

Attributes

Core fields

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

FieldTypeRequiredSourceDescriptionValidation
idstring
Required
System-generatedPrimary identifier for the document (UUID). Automatically generated when the invoice is created.Response-only; not accepted in requests.
org_idstring
Required
System-generatedUnique identifier of the organization that owns this invoice.Set by backend from your organization; not part of the create request body.
document_numberstring
Optional
Conditional (client-provided or system-generated)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_sequencelong
Optional
System-generatedSequential number for the invoice within your organization. Used for compliance and tracking.Server-calculated sequence; do not send on create.
issue_datestring
Required
Client-providedThe date when the invoice was issued.Format yyyy-MM-dd; must be a valid calendar date.
issue_timestring
Optional
Client-providedThe time when the invoice was issued.If present, format HH:mm:ss (e.g. 10:30:00).
invoice_type_codestring
Required
Client-providedThe type of invoice.For purchase invoices created via API, this must be 389 (Self-billed Invoice).
due_datestring
Required
Client-providedThe date when payment is due.Format yyyy-MM-dd.
profile_execution_idstring
Required
Client-providedInvoice transaction type code. See Profile execution ID below.Exactly 8 characters; each character 0 or 1 (binary flags).
document_currency_codestring
Required
Client-providedISO 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_codestring
Optional
Client-providedISO 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_coststring
Optional
Client-providedAccounting cost center / project cost identifier (if applicable).Free text.
buyer_referencestring
Optional
Client-providedBuyer reference (customer reference) for the invoice.Free text.
invoice_periodobject
Optional
Client-providedBilling period covered by the invoice (start_date, end_date, description).If present: start_date and end_date must be yyyy-MM-dd, with start_dateend_date.
notestring
Optional
Client-providedAdditional notes or terms displayed on the invoice.Free text.
tax_point_datestring
Optional
Conditional (client-provided or system-generated default)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_partyobject
Required
Conditional (usually system-generated from profile)The supplier party for the invoice. See Party object below.For purchase invoice API, typically derived from profiles; if sent, must be a valid Party.
accounting_customer_partyobject
Required
Client-providedThe customer party for the invoice. See Party object below.Must be a valid Party object; required in create requests.
buyer_customer_partyobject
Optional
Client-providedUAE 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_partyobject
Optional
Client-providedUAE 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_partyobject
Optional
Client-providedThe 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_partyobject
Optional
Client-providedParty 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).
deliveryobject
Optional
Client-providedWhere and when the goods or services are delivered. See Delivery object below.If present: delivery_location and its address must be populated; may be mandatory for exports.
order_referenceobject
Optional
Client-providedReference to the purchase order. See Order reference object below.If present: id must be provided; issue_date as yyyy-MM-dd when used.
billing_referencearray
Optional
Client-providedReferences 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_referenceobject
Optional
Client-providedReference to despatch/delivery document. See Despatch document reference object below.If present: id required; issue_date yyyy-MM-dd when provided.
receipt_document_referenceobject
Optional
Client-providedReference to receipt document. See Receipt document reference object below.If present: id required; issue_date yyyy-MM-dd when provided.
statement_document_referenceobject
Optional
Client-providedReference to statement document.If present: id required; issue_date yyyy-MM-dd when provided.
originator_document_referenceobject
Optional
Client-providedReference to originating document (when applicable).If present: id required; issue_date yyyy-MM-dd when provided.
contract_document_referenceobject
Optional
Client-providedReference to contract. See Contract document reference object below.If present: id required; issue_date yyyy-MM-dd when provided.
project_referenceobject
Optional
Client-providedProject associated with the invoice. See Project reference object below.If present: id must be provided.
document_linesarray
Required
Client-providedInvoice line items. See Document line object below.Must contain at least one line; each line must satisfy the Document line object validation rules.
chargesarray
Optional
Client-providedDocument-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.
allowancesarray
Optional
Client-providedDocument-level discounts/allowances. See Allowance object below.If present: each allowance must have a valid reason and amount/rate; tax category rules apply.
payment_meansobject
Optional
Client-providedPayment method. See Payment means object below.Required when profile_execution_id first bit is 0; optional when first bit is 1. Certain codes require card or mandate details.
payment_termsobject
Optional
Client-providedPayment terms and conditions. See Payment terms object below.Free structure with date fields in yyyy-MM-dd when used.
tax_exchange_rateobject
Optional
Client-providedExchange 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_amountnumberClient-providedTotal prepaid amount applied to the invoice.Optional numeric; typically non-negative.
payable_rounding_amountnumberClient-providedRounding adjustment applied to payable amount.Optional numeric; may be positive or negative depending on rounding direction.
allowance_total_amountnumberCalculatedTotal of all document-level allowances.Response-only, calculated from document-level allowances.
charge_total_amountnumberCalculatedTotal of all document-level charges.Response-only, calculated from document-level charges.
line_extension_amountnumberCalculatedSum of all line amounts before charges, allowances, and taxes. UBL 2.1 LineExtensionAmount.Response-only, derived from line net amounts.
tax_exclusive_amountnumberCalculatedLine extension plus charges minus allowances, before tax. UBL 2.1 TaxExclusiveAmount.Response-only, calculated.
tax_amountnumberCalculatedAggregated VAT amount in document currency. UBL 2.1 TaxTotal.Response-only, calculated from tax breakdown.
tax_amount_in_aednumberCalculatedTotal tax amount converted to AED.Response-only, calculated using tax exchange rate (if applicable).
tax_inclusive_amountnumberCalculatedTax exclusive amount plus total tax. UBL 2.1 TaxInclusiveAmount.Response-only, calculated.
payable_amountnumberCalculatedFinal amount due. UBL 2.1 PayableAmount.Response-only, calculated as tax inclusive minus prepayments/rounding.
payable_amount_in_aednumberCalculatedFinal amount payable in AED.Response-only, calculated using exchange rates.
total_item_allowancesnumberCalculatedTotal of all line-level allowances.Response-only, sum over line-level allowances.
total_item_chargesnumberCalculatedTotal of all line-level charges.Response-only, sum over line-level charges.
total_taxable_amountnumberCalculatedTotal taxable amount.Response-only, derived from taxable lines and charges/allowances.
total_non_taxable_amountnumberCalculatedTotal non-taxable amount.Response-only, derived from non-taxable lines.
tax_breakdownarrayCalculatedTax 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_sourcestringSystem-generatedSource of the invoice: API, BULK_UPLOAD, PEPPOL, or UI.For Purchase Invoice API, this is always API in requests and responses.
is_phase2_documentbooleanSystem-generatedWhether the document is Peppol-enabled (Phase 2).Response-only flag; controlled by backend/Peppol integration.
meta_infoobject
Optional
System-generatedAdditional 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:

FieldTypeRequiredDescriptionValidation
namestring
Required
Party name or display name.Must be non-empty text.
party_namestring
Required
Legal name of the party.Must be non-empty text.
profile_idstring
Optional
Business profile identifier when referencing a registered profile.If provided, must match an existing business profile.
postal_addressobject
Required
Postal address. See Address object.Required; must satisfy address object validation.
scheme_agency_idstring
Optional
Scheme agency identifier.If present, must be one of TL, EID, PAS, CD, OTH. See Get Registration Types.
company_idstring
Optional
Company or registration number.Free-form registration number; may be validated per jurisdiction.
party_tax_schemeobject
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_idstring
Optional
Peppol endpoint identifier.If present, must be a valid Peppol endpoint for Phase 2 documents.
endpoint_scheme_idstring
Optional
Peppol endpoint scheme identifier.If present, must be a valid Peppol scheme id. See Get Electronic Address Schemes.
emailstring
Optional
Party email address.Free text when provided.
telephonestring
Optional
Party telephone number.Free text when provided.
Address object

Postal and delivery addresses use the shared address object structure.

FieldTypeRequiredDescriptionValidation
street_namestring
Required
Street name or primary address line (UBL address line 1).Must not be blank.
additional_street_namestring
Optional
Additional street name or address line 2.Free text when provided.
city_namestring
Required
City or town name.Must not be blank.
postal_zonestring
Optional
Postal or ZIP code.Free text when provided.
country_subentitystring
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_linestring
Optional
Additional unstructured address line.Free text when provided.
countrystring
Required
Country name (e.g. United Arab Emirates).Must not be blank.
country_codestring
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.

FieldTypeRequiredDescriptionValidation
idstring
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.
percentnumber
Optional
VAT rate as a percentage (e.g. 5 for 5%).Should align with the selected id.
tax_exemption_reason_codestring
Conditional
FTA tax exemption reason code.Required when id is E (exempt). See Get Tax Exemption Reason Codes.
tax_exemption_reasonstring
Optional
Tax exemption reason description.Free text when provided; often used with tax_exemption_reason_code.
tax_schemestring
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.

FieldTypeRequiredDescriptionValidation
idstring
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.

FieldTypeRequiredDescriptionValidation
idstring
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:

FieldTypeRequiredDescriptionValidation
party_identificationobject
Optional
Payee identification.Optional; structure depends on your implementation.
party_namestring
Optional
Name of the payee.If provided, must be non-empty text.
financial_accountobject
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:

FieldTypeRequiredDescriptionValidation
party_identificationobject
Optional
Tax representative identification.Optional; should uniquely identify the tax representative where used.
party_namestring
Optional
Name of the tax representative.If provided, must be non-empty.
postal_addressobject
Optional
Address of the tax representative.If present, see Address object.
Delivery object

The delivery field is an object with the following attributes:

FieldTypeRequiredDescriptionValidation
delivery_locationobject
Optional
Location where goods or services are delivered.If present, must include an address with valid address fields; required for exports.
delivery_datestring
Optional
Date of delivery.If present, format yyyy-MM-dd.
delivery_timestring
Optional
Time of delivery.If present, format HH:mm:ss.
actual_delivery_datestring
Optional
Actual date of delivery.If present, format yyyy-MM-dd.
Order reference object

The order_reference field is an object with the following attributes:

FieldTypeRequiredDescriptionValidation
idstring
Required
Order number or identifier.Must be non-empty when the object is present.
issue_datestring
Optional
Order date.If present, format yyyy-MM-dd.
sales_order_idstring
Optional
Sales order identifier.Free-form identifier.
Billing reference object

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

FieldTypeRequiredDescriptionValidation
idstring
Required
Referenced document number.Must be non-empty when the entry is present.
issue_datestring
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:

FieldTypeRequiredDescriptionValidation
idstring
Required
Despatch document number.Must be non-empty when the object is present.
issue_datestring
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:

FieldTypeRequiredDescriptionValidation
idstring
Required
Receipt document number.Must be non-empty when the object is present.
issue_datestring
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:

FieldTypeRequiredDescriptionValidation
idstring
Required
Statement document number.Must be non-empty when the object is present.
issue_datestring
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:

FieldTypeRequiredDescriptionValidation
idstring
Required
Originating document number or identifier.Must be non-empty when the object is present.
issue_datestring
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:

FieldTypeRequiredDescriptionValidation
idstring
Required
Contract number or identifier.Must be non-empty when the object is present.
issue_datestring
Optional
Contract date.If present, format yyyy-MM-dd.
Project reference object

The project_reference field is an object with the following attributes:

FieldTypeRequiredDescriptionValidation
idstring
Required
Project identifier.Must be non-empty when the object is present.
namestring
Optional
Project name.Free text.
Price object

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

FieldTypeRequiredDescriptionValidation
base_amountnumber
Required
Item net price.Must not be negative.
base_quantitynumber
Required
Item price base quantity.Must be positive.
allowance.amountnumber
Optional
Price level discount.Must not be negative when provided.
Document line object

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

FieldTypeRequiredDescriptionValidation
namestring
Required
Line item name.Must be non-empty.
descriptionstring
Optional
Line item description.Free text.
unit_codestring
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.
quantitynumber
Required
Quantity.Must be a positive number.
priceobject
Required
Line item price. See Price object.Must satisfy Price object validation.
base_amountnumber
Optional
Calculated base amount.Response-only; calculated as quantity × price.
net_amountnumber
Optional
Net amount.Response-only; calculated.
total_amountnumber
Optional
Total including tax.Response-only; calculated.
tax_amountnumber
Optional
Tax amount for the line.Response-only; calculated from line tax.
classified_tax_categoryobject
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:

FieldTypeRequiredDescriptionValidation
charge_reason_codestring
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.
amountnumber
Required
Charge amount.Must be numeric, usually ≥ 0.
base_amountnumber
Optional
Base amount for the charge.If used with percentages, must be provided consistently with multiplier/factor logic in your profile.
tax_categoryobject
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:

FieldTypeRequiredDescriptionValidation
reasonstring
Conditional
Free-text allowance reason.At least one of reason or reason_code must be provided. Free text when provided.
reason_codestring
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.
amountnumber
Required
Allowance amount.Must be numeric, usually ≥ 0.
base_amountnumber
Optional
Base amount for the allowance.If used with percentages, must be provided consistently with multiplier/factor logic in your profile.
tax_categoryobject
Optional
Tax category for allowance adjustment.If present, see Tax category object. tax_exemption_reason_code required when id is E.
Payment means object

The payment_means field is an object with the following attributes:

FieldTypeRequiredDescriptionValidation
payment_means_codestring
Required
Payment means code (e.g. 54 for credit card).Must be one of: 1, 10, 20, 21, 30, 49, 54, 55, 68.
payment_idstring
Optional
Payment reference or identifier.Free text; may be used for reconciliation.
card_accountobject
Optional
Card details. Contains primary_account_number_id, network_id.Required when payment_means_code is 54 or 55; must include valid masked PAN and network id.
financial_accountobject
Optional
Bank/financial account details.Required for credit transfer scenarios (payment_means_code 30).
Payment terms object

The payment_terms field is an object with the following attributes:

FieldTypeRequiredDescriptionValidation
notestring
Optional
Payment terms description.Free text.
due_datestring
Optional
Payment due date.If present, format yyyy-MM-dd.
installment_due_datestring
Optional
Installment due date.If present, format yyyy-MM-dd.
amountnumber
Optional
Amount due.Must be numeric if provided.
Tax exchange rate object

The tax_exchange_rate field is an object with the following attributes:

FieldTypeRequiredDescriptionValidation
source_currency_codestring
Required
Source currency (ISO 4217).Must be a valid ISO 4217 code. See Get Currency Names and Codes.
target_currency_codestring
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_ratenumber
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:

FieldTypeRequiredDescriptionValidation
peppol_statusobject
Optional
Peppol participant/FTA processing status.Response-only; see Peppol status object below.
Peppol status object

The meta_info.peppol_status field is an object with the following attributes:

FieldTypeRequiredDescriptionValidation
participant_statusstring
Optional
Participant-level processing status.Must be one of the status values listed below.
fta_statusstring
Optional
FTA submission/processing status.Must be one of the status values listed below.
overall_statusstring
Optional
Overall Peppol processing status.Must be one of the status values listed below.
validation_resultsarray
Optional
Validation details/errors returned during processing.Response-only list; empty when there are no validation issues.
Status values
ValueMeaning
VALIDATION_FAILEDThe received document failed validation checks.
PENDINGProcessing is in progress.
APPROVEDThe document is accepted.
REJECTEDThe document is processed but rejected.
Client processing guidance:
  1. Treat overall_status as the primary state for workflow decisions.

  2. Use participant_status and fta_status as stage-specific diagnostics for UI and support logs.

  3. If overall_status is PENDING, keep the invoice in a processing state and poll/re-fetch later.

  4. If overall_status is APPROVED, mark the Peppol flow as successful and continue normal downstream actions.

  5. If overall_status is REJECTED or VALIDATION_FAILED, stop submission-dependent actions and surface the failure to users.

  6. When validation_results is not empty, display user-friendly error summaries from text, and retain flag, reasonCode, location, and test for troubleshooting.

  7. participant_status or fta_status can be null in early/failed validation stages; do not treat null alone as success or failure.

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.

When the first character is 0, payment_means is required. When it is 1 (Free Trade Zone), payment_means is optional.

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

Transaction typePositionWhen the flag is 1
Free Trade Zone1XXXXXXXSet buyer_customer_party.id (Beneficiary TIN). See Buyer customer party object. Example payload: Example 5: Free Trade Zone.
Deemed SupplyX1XXXXXXNo additional mandatory fields beyond standard validation.
Profit Margin SchemeXX1XXXXXNo additional mandatory fields beyond standard validation.
Summary InvoiceXXX1XXXXSet invoice_period.start_date, invoice_period.end_date, and invoice_period.description. Example payload: Example 6: Summary invoice.
Continuous SupplyXXXX1XXXNo additional mandatory fields beyond standard validation.
Disclosed Agent BillingXXXXX1XXSet seller_supplier_party.id (Principle ID TRN). See Seller supplier party object. Example payload: Example 7: Disclosed agent billing.
Supply through e-commerceXXXXXX1XInclude delivery with delivery_location.address. See Delivery object.
ExportsXXXXXXX1Include 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.*

ScenarioTypical profile_execution_idExamples page
Standard invoice (baseline)00000000Example 1: Minimal purchase invoice
Free Trade Zone10000000Example 5: Free Trade Zone
Summary invoiceXXX1XXXX (flag in position 4)Example 6: Summary invoice
Disclosed agent billingXXXXX1XX (flag in position 6)Example 7: Disclosed agent billing
Export / e-commerce deliveryXXXXXX1X or XXXXXXX1Example 8: Export transaction
Next