MarminDeveloper Docs
BusinessesPartnersProduct Wiki

Create a sales invoice

Creates a sales invoice conforming to UBL 2.1 with PINT AE customization. See the right panel for request samples and response JSON.

Path parameters
ParameterTypeRequiredDescription
business_profile_idstring
Required
The business profile ID of the supplier issuing the invoice. Must exist in your organization.
Required data

  • Customer party objects — Complete accounting customer party with name, address, and tax scheme when required

  • Business profile identifier — Business profile ID of the supplier (in path)

  • Business profile identifier — Must exist in your organization

  • Line items — At least one document line with name, quantity, unit code, price, and classified tax category

  • VAT information — Tax category and scheme per line and for charges/allowances as applicable

System behavior

  • VAT rules are applied according to UAE VAT law

  • The sales invoice is recorded

  • Invoice status and transmission events are tracked

Validation rules
RuleDescription
Profile execution IDMust match pattern ^[0-1]{8}$
Invoice Type CodeMust 380 or 480
Payment meansRequired if profile execution ID position 1 (second character) is 0
UAE addressesMust include country_subentity (emirate code: DXB, AUH, SHJ, etc.)
Tax schemeMust be VAT for UAE parties
TRN formatValidation per FTA specifications (15 digits for UAE)
Document numberMust be unique within organization (if provided)
Business profile IDMust exist in your organization
PermissionsUser must have permission to create invoices for the specified business profile
Response

Status code: 201 Created

The API returns an invoice object containing all request fields plus calculated fields.

System-generated fields
FieldDescription
idUnique identifier
uuidUUID for Peppol network integration
document_numberInvoice number (auto-generated if auto-numbering enabled)
document_sequenceSequential number within organization
Calculated monetary totals
FieldDescription
line_extension_amountSum of all line item amounts before tax
tax_exclusive_amountTotal before tax (line extension + charges − allowances)
tax_amountTotal VAT amount
tax_amount_in_aedTotal VAT amount in AED (if different currency used)
tax_inclusive_amountTotal including tax
payable_amountFinal amount to be paid
payable_amount_in_aedFinal amount in AED (if different currency used)
allowance_total_amountTotal of all document-level allowances
charge_total_amountTotal of all document-level charges
total_item_allowancesTotal of all line-level allowances
total_item_chargesTotal of all line-level charges
total_taxable_amountTotal taxable amount
total_non_taxable_amountTotal non-taxable amount
Additional response fields
FieldDescription
tax_breakdownTax amounts grouped by tax category
is_phase2_documentWhether document is Phase 2 (Peppol-enabled)
meta_infoCreation timestamp, status, peppol_status, etc.
Document lines in response

Each line includes calculated fields: base_amount, net_amount, total_amount, tax_amount. The price object in the response contains price_amount (instead of base_amount in the request).

Charges and allowances

  • Document-level charges and allowances are applied after line item totals

  • Line-level charges and allowances are applied per line item

  • All charges and allowances require a tax_category for proper VAT calculation

  • The reason code field uses UN/ECE Recommendation 20 codes (e.g. FC for freight charges, 95 for early payment discount, 100 for volume discount)

See the right panel for complete response examples.

Error responses
StatusDescription
400 Bad RequestInvalid request parameters or validation failed. For validation errors, the response includes field-specific errors.
401 UnauthorizedAuthentication required or invalid token.
413 Request Entity Too LargeThe request payload size exceeds the allowed limit of 8MB.
500 Internal Server ErrorAn error occurred while processing the request.
Next