Marmin
BusinessesPartnersProduct Wiki

Export transaction with delivery

Use this payload when the export flag is enabled in profile_execution_id.

When to use it

  • The last character of profile_execution_id is 1.

  • Goods or services are supplied to a non-UAE buyer and delivery details must be present.

Contract reference

Field definitions below are taken from The sale invoice object. Only tables relevant to this example are shown.

Core fields

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

Root-level fields used in this example.

FieldTypeRequiredDescriptionValidation
issue_datestring
Required
The date when the invoice was issued.Format yyyy-MM-dd; must be a valid calendar date.
issue_timestring
Optional
The time when the invoice was issued.If present, format HH:mm:ss (e.g. 10:30:00).
invoice_type_codestring
Required
The type of invoice.Must be one of 380 or 480.
due_datestring
Required
The date when payment is due.Format yyyy-MM-dd.
profile_execution_idstring
Required
Invoice transaction type code. See Profile execution ID below.Exactly 8 characters; each character 0 or 1 (binary flags).
document_currency_codestring
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.
accounting_customer_partyobject
Required
The customer party receiving the invoice. See Party object below.Must be a valid Party object; required in create requests.
deliveryobject
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 flag applies (profile_execution_id ends with 1).
document_linesarray
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_meansarray
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, account, or mandate details.
document_sourcestring—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.

FieldTypeRequiredDescriptionValidation
namestring
Required
Party name or display name.Must be non-empty text.
party_namestring
Conditional
Legal name of the party.Required for business parties. Do not send for individual customers.
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
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.
company_idstring
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 sent.
authority_namestring
Optional
Issuing authority for the trade license.Optional. Required only when scheme_agency_id is TL and registration details are included.
passport_issuing_country_codestring
Optional
Country that issued the passport.Optional. Required only when scheme_agency_id is PAS and registration details are included.
tinstring
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_schemeobject
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, pattern ^1\d{12}0(01\|3)$. 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_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
Required
Party email address.Required for customer and supplier parties.
telephonestring
Conditional
Party telephone number.Required for UAE suppliers. Optional for customers.
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.
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 (ibt-146).Must not be negative.
base_quantitynumber
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).
allowanceobject
Optional
Price-level allowance (discount on the item net price).If present, see price allowance below.
allowance.amountnumber
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.

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

FieldTypeRequiredDescriptionValidation
namestring
Required
Item name (ibt-153): a name for the item.Must be non-empty.
descriptionstring
Required
Item description (ibt-154): a description for the item.Must be non-empty.
quantitynumber
Required
Invoiced quantity (ibt-129).Must be a positive number.
unit_codestring
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.
priceobject
Required
Item net price details. See Price object.Must satisfy Price object validation.
classified_tax_categoryobject
Required
Line VAT information: VAT applicable for the goods and services invoiced on this line. See Tax category object.Must satisfy Tax category object validation; tax_exemption_reason_code and tax_exemption_reason are required when id is E.
notestring
Optional
Free-text note for the line.Free text.
accounting_coststring
Optional
Accounting cost center for this line.Free text.
invoice_periodobject
Optional
Line invoicing period (ibt-134, ibt-135). See Invoice period object.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_referenceobject
Optional
Invoice line identifier (ibt-126). See Order line reference object.Required for compliance (IBR-021): must include line_id when sent.
despatch_line_referenceobject
Optional
Reference to a despatch document line. See Despatch line reference object.If present, must be valid.
document_referenceobject
Optional
Reference to a related document for this line. See Line document reference object.If present: id required.
chargesarray
Optional
Line-level charges that increase the line amount. See Charge object.If present: each item must include reason or reason_code. tax_category is optional at line level.
allowancesarray
Optional
Line-level allowances (discounts) on the line. See Allowance object.If present: each item must include reason or reason_code. tax_category is optional at line level.
buyer_item_identificationobject
Optional
Buyer's item identification: an identifier assigned by the buyer for the item. See Buyer item identification object.If present: must include id.
seller_item_identificationobject
Optional
Seller's item identification: an identifier assigned by the seller for the item. See Seller item identification object.If present: must include id.
standard_item_identificationobject
Optional
Standard item identification (ibt-157): an item identifier based on a registered scheme. See Standard item identification object.If present: must include id and scheme_id (IBR-064).
additional_item_identificationarray
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_countryobject
Optional
Origin country: country of origin for the item. See Origin country object.If present: must include a valid country identification code.
commodity_classificationobject
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_propertyarray
Optional
Item attributes: properties of the goods and services invoiced on this line. See Additional item property object.If present: each item must include name and value.
lot_number_idstring
Optional
Batch number: an identifier for the production batch or lot that the items come from.Free text.
line_object_identifierstring
Optional
Internal line object identifier used by your integration.Free text.
base_amountnumber—Extended quantity × unit price before tax, charges, and allowances.Response-only; do not send on create.
net_amountnumber—Invoice line net amount (ibt-131).Response-only; do not send on create.
total_amountnumber—Line total including tax.Response-only; do not send on create.
tax_amountnumber—VAT amount for this line.Response-only; do not send on create.
total_amount_in_aednumber—Line total in AED when document currency differs.Response-only; do not send on create.
tax_amount_in_aednumber—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:

FieldTypeRequiredDescriptionValidation
idstring
Optional
Payment means identifier.Optional identifier for the payment instruction.
payment_means_codestring
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.
payment_idarray of strings
Optional
Payment reference identifiers.Used for payment reconciliation.
card_accountobject
Conditional
Card account details.Mandatory when payment_means_code is 54 or 55.
payee_financial_accountobject
Conditional
Payee bank/financial account details.Mandatory when payment_means_code is 30.
payment_mandateobject
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:

FieldTypeRequiredDescriptionValidation
primary_account_number_idstring
Required
Primary account number identifier. UI label: PAN.Mandatory when payment_means_code is 54 or 55; must not be blank.
network_idstring
Required
Card network identifier. UI label: Network ID.Mandatory when payment_means_code is 54 or 55; must not be blank.
holder_namestring
Optional
Card holder name.Free text.
Payee financial account object

The payee_financial_account field is an object with the following attributes:

FieldTypeRequiredDescriptionValidation
idstring
Optional
Payee financial account identifier. UI label: Payment account identifier.Mandatory when payment_means_code is 30.
namestring
Optional
Payee financial account name.Free text.
financial_institution_branch_idstring
Optional
Financial institution branch identifier.Free text.
addressobject
Optional
Payee financial account address.If present, see Address object.
Payment mandate object

The payment_mandate field is an object with the following attributes:

FieldTypeRequiredDescriptionValidation
idstring
Optional
Payment mandate identifier. UI label: Mandate reference Identifier.Mandatory when payment_means_code is 49.
payer_financial_account_idstring
Optional
Payer financial account identifier. UI label: Payer Financial Account Identifier.Mandatory when payment_means_code is 49.
Delivery object

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

FieldTypeRequiredDescriptionValidation
actual_delivery_datestring
Optional
Actual date of delivery.If present, format yyyy-MM-dd.
delivery_locationobject
Required
Where goods or services are delivered. See Delivery location object below.Must be present whenever the delivery object is included.
party_namestring
Optional
Name of the delivery-related party.Free text when provided.
party_idstring
Optional
Identifier of the delivery-related party.Free text when provided.
termsstring
Optional
Delivery terms.Free text when provided.
Delivery location object

The delivery_location object has the following attributes.

FieldTypeRequiredDescriptionValidation
idstring
Optional
Delivery location identifier.Free text when provided.
addressobject
Required
Postal address of the delivery location.Required when delivery_location is present. See Address object.
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 sale 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.

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 under Sale invoice examples.

Transaction typePositionWhen to useWhen the flag is 1
Free trade zone1XXXXXXXSupply of goods or services in a free trade zone.Set buyer_customer_party.id (Beneficiary TIN). See Buyer customer party object. Example payload: Free Trade Zone.
Deemed supplyX1XXXXXXSupply of goods or services without consideration.No additional mandatory fields beyond standard validation.
Profit Margin SchemeXX1XXXXXSupply of goods under the profit margin scheme.No additional mandatory fields beyond standard validation.
Summary invoiceXXX1XXXXTaxable 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 SupplyXXXX1XXXSupply of goods and/or services made on a recurrent basis.No additional mandatory fields beyond standard validation.
Agent billingXXXXX1XXAgent 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. Example payload: Disclosed agent billing.
Supply through e-commerceXXXXXX1XSupply of goods or services via e-commerce.Include delivery with delivery_location.address when required by your business scenario. See Delivery object.
ExportsXXXXXXX1Supply 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. Example payload: Export transaction with delivery.

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

ScenarioTypical profile_execution_idExamples page
Standard invoice (baseline)00000000Minimal sale invoice
Free Trade Zone10000000Free Trade Zone
Summary invoiceXXX1XXXX (flag in position 4)Summary invoice
Disclosed agent billingXXXXX1XX (flag in position 6)Disclosed agent billing
Export deliveryXXXXXXX1Export transaction with delivery

See the example payload in the right-side panel.

Next