API Docs

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.

Rate limit

60 requests/minute per authenticated account. See Rate limiting for response headers (X-RateLimit-*) and retry guidance.

Path parameters

Parameter	Type	Required	Description
`business_profile_id`	string	Required	The business profile ID of the supplier issuing the invoice. Must exist in your organization.

Request body

Send the full sales invoice JSON in the request body. See the right panel for a complete request example.

Request fields

Fields in the request JSON. Rows are ordered Required → Conditional → Optional.

Required fields — always send on create.
Conditionally required fields — required only in some cases; see Validation and Conditional field rules below.
Optional fields — skip unless you need them.

Object fields (for example accounting_customer_party or document_lines) are documented in their own sections further down this page.

Do not send: accounting_supplier_party — the API sets the supplier from {profileId}. Do not send calculated or system fields (id, org_id, document_sequence, totals, meta_info, etc.) — those appear in the response only.

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.
`invoice_type_code`	string	Required	The type of invoice.	Must be `380` or `480`. See Invoice type codes (380 and 480) section for details.
`due_date`	string	Required	The date when payment is due.	Format `yyyy-MM-dd`.
`profile_execution_id`	string	Required	Invoice transaction type code.	Exactly 8 characters; each character `0` or `1`. See Profile execution ID section for details.
`document_currency_code`	string	Required	ISO 4217 alpha-3 currency code for all monetary amounts (e.g. `AED`).	Must be a valid ISO 4217 code. See Get Currency Names and Codes section for details. For non-AED documents, see Non-AED invoices.
`accounting_customer_party`	object	Required	The customer party receiving the invoice.	Must be a valid party object. See Customer party object section for details.
`document_lines`	array	Required	Invoice line items.	At least one line required. See Document line object section for details.
`document_number`	string	Conditional	The invoice number as displayed on the document.	Required when auto-numbering is disabled for your organization; auto-generated when auto-numbering is enabled and the field is omitted. Must be unique within the organization when provided. Recommendation: provide this value explicitly so it matches your ERP, e-invoicing platform, and Marmin for easier reconciliation.
`tax_point_date`	string	Conditional	Tax point date per UAE VAT Law—when VAT liability arises.	If present: format `yyyy-MM-dd`; must be on or before `issue_date`. See Tax point date (UAE VAT) section for details.
`tax_currency_code`	string	Conditional	ISO 4217 currency code for tax amounts.	Optional when `document_currency_code` is `AED`. Required when `document_currency_code` is not `AED`—must be `AED` and differ from `document_currency_code`. If present, must be a valid ISO 4217 code. See Non-AED invoices section for details.
`tax_exchange_rate`	object	Conditional	Exchange rate for tax calculation in AED.	Required when `document_currency_code` is not `AED`. See Tax exchange rate object and Non-AED invoices.
`buyer_customer_party`	object	Conditional	Beneficiary ID (UBL `BTAE-01`). Not a full party object.	Required for Free Trade Zone (FTZ). See Buyer customer party object section for details.
`seller_supplier_party`	object	Conditional	Principle ID (UBL `BTAE-14`). Not a full party object.	Required for Disclosed Agent Billing. See Seller supplier party object section for details.
`delivery`	object	Conditional	Delivery details.	Required for Exports. If included otherwise, see Delivery object.
`payment_means`	array	Conditional	Payment method.	Required unless Deemed supply applies. See Payment means array section for details.
`invoice_period`	object	Conditional	Billing period covered by the invoice.	Required for Summary invoice. If included otherwise, see Invoice period object.
`issue_time`	string	Optional	The time when the invoice was issued.	Format `HH:mm:ss` (e.g. `10:30:00`). Must be Gulf Standard Time (GST, UTC+4). When omitted, the API defaults to `00:00:00` (midnight GST).
`accounting_cost`	string	Optional	Accounting cost center / project cost identifier.	Free text.
`buyer_reference`	string	Optional	Buyer reference (customer reference) for the invoice.	Free text.
`note`	string	Optional	Additional notes or terms displayed on the invoice.	Free text.
`payee_party`	object	Optional	Party to whom payment should be made, if different from the supplier.	If present, see Payee party object.
`tax_representative_party`	object	Optional	Party authorized to represent the supplier for tax purposes.	If present, see Tax representative party object.
`order_reference`	object	Optional	Reference to the purchase order.	If present, see Order reference object.
`billing_reference`	array	Optional	References to other billing documents.	If present, see Billing reference object.
`despatch_document_reference`	object	Optional	Reference to despatch/delivery document.	If present, see Despatch document reference object.
`receipt_document_reference`	object	Optional	Reference to receipt document.	If present, see Receipt document reference object.
`statement_document_reference`	object	Optional	Reference to statement document.	If present: `id` required; `issue_date` as `yyyy-MM-dd` when provided.
`originator_document_reference`	object	Optional	Reference to originating document.	If present: `id` required; `issue_date` as `yyyy-MM-dd` when provided.
`contract_document_reference`	object	Optional	Reference to contract.	If present, see Contract document reference object.
`project_reference`	object	Optional	Project associated with the invoice.	If present, see Project reference object.
`charges`	array	Optional	Document-level charges.	If present, see Charge object.
`allowances`	array	Optional	Document-level discounts/allowances.	If present, see Allowance object.
`payment_terms`	object	Optional	Payment terms and conditions.	If present, see Payment terms object.
`prepaid_amount`	number	Optional	Total prepaid amount applied to the invoice.	Typically non-negative.
`payable_rounding_amount`	number	Optional	Rounding adjustment applied to payable amount.	May be positive or negative.
`document_source`	string	Optional	Origin of the e-invoice document (e.g. `SAP_S4HANA`, `Oracle_NetSuite`).	Defaults to `API` when omitted.
`attachments`	array	Optional	Supporting documents attached to the invoice.	If present, see Attachment object (request). Entire create POST body must not exceed 8 MB.

Conditional field rules

Condition	Affected fields	Rule
Free Trade Zone (FTZ)	`buyer_customer_party.id`	Required — valid Beneficiary TIN.
Summary invoice	`invoice_period`	Object required (`IBR-138-AE`); at least one of `start_date` or `end_date` required (`IBR-CO-19`); `description` optional.
Disclosed Agent Billing	`seller_supplier_party.id`	Required — valid Principle ID TRN.
Supply through e-commerce	`delivery`	Required with `street_name`, `city_name`, `country_subentity`, and `country_code`.
Exports	`delivery`	Required with `street_name`, `city_name`, `country_subentity`, and `country_code` (must not be `AE`).
Deemed supply	`payment_means`	May be omitted.
Not deemed supply	`payment_means`	At least one payment means required.
`document_currency_code` ≠ `AED`	`tax_currency_code`, `tax_exchange_rate`	See Non-AED invoices section for details.
Invoice out of scope (480)	Line, charge, and allowance tax categories	Use `E`, `Z`, or `O` only (not `S`, `AE`, or `N`).

Customer party object

The accounting_customer_party field on create and resubmit requests. The supplier (accounting_supplier_party) is set automatically from the {profileId} business profile—do not send it.

Field requirements depend on customer type and address. See The Customer party object section for details.

Field	Type	Required	Description	Validation
`name`	string	Required	Party name or display name.	Must be non-empty text.
`postal_address`	object	Required	Postal address. See Address object section for details.	Required; must satisfy address object validation.
`email`	string	Required	Party email address.	Required for customer and supplier parties.
`party_name`	string	Conditional	Legal name of the party.	Required for business parties. Do not send for individual customers.
`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.
`telephone`	string	Conditional	Party telephone number.	Required for UAE suppliers. Optional for customers.
`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.
`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 digits; starts with `1` and ends with `03`.
`endpoint_id`	string	Required	Peppol endpoint identifier (participant identification).	Required on every document. Use the party's 10-digit TIN when Peppol-registered. For deemed supply, exports, or non-compliant parties, see Endpoint identification reference. Must be a valid Peppol endpoint for Phase 2 documents.
`endpoint_scheme_id`	string	Required	Peppol endpoint scheme identifier (participant scheme ID). Typically `0235` for UAE.	Required on every document. See Endpoint identification reference and Get Electronic Address Schemes section for details

Response party fields

Field	Type	Source	Description
`profile_id`	string	System Provided	Business profile identifier on the party object.

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.
`city_name`	string	Required	City or town name.	Must not be blank.
`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.
`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.
`additional_street_name`	string	Optional	Additional street name or address line 2.	Free text when provided.
`postal_zone`	string	Optional	Postal or ZIP code.	Free text when provided.
`address_line`	string	Optional	Additional unstructured address line.	Free text 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.
`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.
`percent`	number	Optional	VAT rate as a percentage (e.g. `5` for 5%).	Should align with the selected `id`.
`tax_scheme`	string	Optional	Tax scheme identifier (typically `VAT` for UAE).	See Get Tax Schemes section for details.

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 for Free Trade Zone (FTZ). 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 for Disclosed Agent Billing. Must be a valid TRN; must differ from the seller VAT identifier on the business profile.

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
`delivery_location`	object	Required	Where goods or services are delivered. See Delivery location object below.	Must be present whenever the `delivery` object is included.
`actual_delivery_date`	string	Optional	Actual date of delivery.	If present, format `yyyy-MM-dd`.
`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	Incoterms (PEPPOL BTAE-22), e.g. `FCA`, `DDP`.	Optional even when `delivery` is present.

Delivery location object

The delivery_location object has the following attributes.

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

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.

Price object

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

Field	Type	Required	Source	Description	Validation
`base_amount`	number	Required	Client-provided	Item net price (ibt-146).	Must not be negative.
`base_quantity`	number	Required	Client-provided	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	Client-provided	Price-level allowance (discount on the item net price).	If present, see price allowance below.
`allowance.amount`	number	Optional	Client-provided	Price-level discount amount.	Must not be negative when provided.

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	Source	Description	Validation
`name`	string	Required	Client-provided	Item name (ibt-153): a name for the item.	Must be non-empty.
`description`	string	Required	Client-provided	Item description (ibt-154): a description for the item.	Must be non-empty.
`quantity`	number	Required	Client-provided	Invoiced quantity (ibt-129).	Must be a positive number.
`unit_code`	string	Required	Client-provided	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	Client-provided	Item net price details. See Price object section for details.	Must satisfy Price object validation.
`classified_tax_category`	object	Required	Client-provided	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`.
`additional_item_identification`	array	Conditional	Client-provided	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`).
`commodity_classification`	object	Conditional	Client-provided	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.
`note`	string	Optional	Client-provided	Free-text note for the line.	Free text.
`accounting_cost`	string	Optional	Client-provided	Accounting cost center for this line.	Free text.
`invoice_period`	object	Optional	Client-provided	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	Client-provided	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	Client-provided	Reference to a despatch document line. See Despatch line reference object section for details.	If present, must be valid.
`document_reference`	object	Optional	Client-provided	Reference to a related document for this line. See Line document reference object section for details.	If present: `id` required.
`charges`	array	Optional	Client-provided	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	Client-provided	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	Client-provided	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	Client-provided	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	Client-provided	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`).
`origin_country`	object	Optional	Client-provided	Origin country: country of origin for the item. See Origin country object section for details.	If present: must include a valid country identification code.
`additional_item_property`	array	Optional	Client-provided	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	Client-provided	Batch number: an identifier for the production batch or lot that the items come from.	Free text.
`line_object_identifier`	string	Optional	Client-provided	Internal line object identifier used by your integration.	Free text.

Invoice period object

Used at document level (invoice_period) and on document lines (document_lines[].invoice_period). If you include this object, all sub-field conditions below apply.

Context	`start_date`	`end_date`	`description`
Object omitted	—	—	—
Object present (general)	At least one of `start_date` or `end_date` required	Same	Optional
Both dates sent	Required pair; `start_date` ≤ `end_date`	Required pair	Optional
Summary invoice	At least one of `start_date` or `end_date` required (`IBR-CO-19`)	Same	Optional
Line-level `document_lines[].invoice_period`	Must fall within document-level period when both exist (`IBR-085`, `IBR-086`)	Same	—

Field	Type	Required	Description	Validation
`start_date`	string	Conditional	Invoicing period start date (ibt-073 at document level; ibt-134 on lines).	Format `yyyy-MM-dd`. Best practice: send both `start_date` and `end_date` together.
`end_date`	string	Conditional	Invoicing period end date (ibt-074 at document level; ibt-135 on lines).	Format `yyyy-MM-dd`; if both dates are sent, must be ≥ `start_date`.
`description`	string	Optional	Frequency of billing for the period (UBL BTAE-06).	If present: must be a value from the frequency of billing code list — codes `DLY`, `WKY`, `Q15`, `MTH`, `Q45`, `Q60`, `QTR`, `YRL`, `HYR`, `OTH` or names `Daily`, `Weekly`, `Once in 15 days`, `Monthly`, `Once in 45 days`, `Once in 60 days`, `Quarterly`, `Yearly`, `Half-Yearly`, `Others`. When `OTH`/`Others`, document `note` is required.

Order line reference object

Field	Type	Required	Source	Description	Validation
`line_id`	string	Required	Client-provided	Invoice line identifier (ibt-126).	Must be non-empty when the object is present.
`order_reference_id`	string	Optional	Client-provided	Related order reference identifier for this line.	Free text.

Despatch line reference object

Field	Type	Required	Source	Description	Validation
`line_id`	string	Required	Client-provided	Despatch document line identifier.	Must be non-empty when the object is present.

Line document reference object

Field	Type	Required	Source	Description	Validation
`id`	string	Required	Client-provided	Referenced document identifier.	Must be non-empty when the object is present.
`issue_date`	string	Optional	Client-provided	Referenced document issue date.	If present, format `yyyy-MM-dd`.

Buyer item identification object

The buyer_item_identification field is an object with the following attributes:

Field	Type	Required	Source	Description	Validation
`id`	string	Required	Client-provided	Item buyer's identifier: an identifier, assigned by the buyer, for the item.	Must be non-empty when the object is present.

Seller item identification object

The seller_item_identification field is an object with the following attributes:

Field	Type	Required	Source	Description	Validation
`id`	string	Required	Client-provided	Item seller's identifier: an identifier, assigned by the seller, for the item.	Must be non-empty when the object is present.

Standard item identification object

The standard_item_identification field is an object with the following attributes:

Field	Type	Required	Source	Description	Validation
`id`	string	Required	Client-provided	Item standard identifier: an item identifier based on a registered scheme.	Must be non-empty when the object is present.
`scheme_id`	string	Required	Client-provided	Scheme identifier: the identification scheme identifier of the item standard identifier.	Must be a valid ISO 6523 ICD scheme (`IBR-CL-21`).

Additional item identification object

Use this array for Service Accounting Code (SAC) when the line Item Type is Services (S) or Both (B). In Marmin UI this is the Service Accounting Code field—not the Item Type dropdown.

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

Field	Type	Required	Source	Description	Validation
`id`	string	Required	Client-provided	Service Accounting Code (SAC): classifies the service by type or nature.	Must be non-empty when the object is present.
`scheme_id`	string	Required	Client-provided	SAC scheme identifier.	Must be `"SAC"` when SAC is provided (`IBR-189-AE`).
`scheme_version_id`	string	Optional	Client-provided	SAC scheme version identifier.	Free text when provided.

Line item classification (UI to API)

The tables below map common ERP/UI labels on a document line to the API fields on document_lines[]. Use them when building create payloads from your source system.

#### Item type

Layer	Name / value
UI label	Item Type
Form field	`commodity_code`
UI values	`G` = Goods, `S` = Services, `B` = Both
API (per line)	`commodity_classification.commodity_code`

#### Item classification identifier (HSN)

Applies when Item Type is Goods (`G`) or Both (`B`).

Layer	Name / value
UI label	Item Classification Identifier
Form field	`item_classification_identifier.code` (optional `description`)
API (per line)	`commodity_classification.item_classification_code` — HSN code string

#### Service accounting code (SAC)

Applies when Item Type is Services (`S`) or Both (`B`).

Layer	Name / value
UI label	Service Accounting Code
API (per line)	`additional_item_identification[].id` with `scheme_id`: `"SAC"`

#### Related fields

UI / form	API	Purpose
Item Type (`commodity_code`)	`commodity_classification.commodity_code`	Goods / Services / Both
Item Classification Identifier	`commodity_classification.item_classification_code` + `item_classification_list_id`: `"HS"`	HSN for goods
Service Accounting Code (Services / Both)	`additional_item_identification[].id` with `scheme_id`: `"SAC"`	SAC for services
`nature_code` (separate; reverse charge)	`commodity_classification.nature_code`	Not the Item Type dropdown

Commodity classification object

The commodity_classification object carries Item Type, HSN (for goods), and reverse-charge metadata. See Line item classification (UI to API) for UI mappings.

Field	Type	Required	Source	Description	Validation
`commodity_code`	string	Conditional	Client-provided	Item type (UI: Item Type). Whether the line is Goods, Services, or Both.	Required when classifying the line. Must be `G`, `S`, or `B`. Maps from UI/form field `commodity_code`.
`item_classification_code`	string	Conditional	Client-provided	Item classification identifier (UI: HSN). Harmonized System code for the goods on this line.	Required when `commodity_code` is `G` or `B` (`IBR-184-AE`). Must be non-empty. Maps from UI `item_classification_identifier.code`.
`item_classification_list_id`	string	Conditional	Client-provided	HSN scheme identifier (UNTDID 7143).	Required when `item_classification_code` is sent. Always `"HS"` for UAE (`IBR-188-AE`).
`item_classification_list_version_id`	string	Optional	Client-provided	HSN scheme version.	Send `null` (do not omit if your serializer requires the key).
`nature_code`	string	Optional	Client-provided	Type of goods or services subject to reverse charge (RCM). Separate from Item Type.	If present, must be a valid RCM nature code (`IBR-166-AE`). Not the Item Type dropdown.

Origin country object

Field	Type	Required	Source	Description	Validation
`identification_code`	string	Required	Client-provided	ISO 3166-1 alpha-2 country code for country of origin.	Must be a valid country code. See Get Countries section for details.

Additional item property object

Field	Type	Required	Source	Description	Validation
`name`	string	Required	Client-provided	Attribute name (e.g. color, size, material).	Must be non-empty when the object is present.
`value`	string	Required	Client-provided	Attribute value.	Must be non-empty when the object is present.

Charge object

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

Field	Type	Required	Description	Validation
`reason`	string	Conditional	Free-text charge reason. Use this for a custom charge reason when no code applies.	At least one of `reason` or `reason_code` must be provided.
`reason_code`	string	Conditional	UN/ECE Recommendation 20 charge reason code.	At least one of `reason` or `reason_code` must be provided. Must be a valid charge reason code (e.g. `FC`). See Get Charge Reason Codes section for details.
`tax_category`	object	Conditional	Tax category applied to the charge.	Required for document-level charges. Optional for line-level charges. If present, see Tax category object. `tax_exemption_reason_code` and `tax_exemption_reason` are required when `id` is `E`.
`amount`	number	Optional	Charge amount.	Numeric amount for the charge.
`multiplier_factor_numeric`	number	Optional	Percentage or multiplier used to calculate the charge.	If sent, `base_amount` must also be sent.
`base_amount`	number	Optional	Base amount for the charge.	If sent, `multiplier_factor_numeric` must also be sent.

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 or discount reason. Use this for a custom reason when no code applies.	At least one of `reason` or `reason_code` must be 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 section for details.
`tax_category`	object	Conditional	Tax category for allowance adjustment.	Required for document-level allowances. Optional for line-level allowances. If present, see Tax category object. `tax_exemption_reason_code` and `tax_exemption_reason` are required when `id` is `E`.
`amount`	number	Optional	Allowance amount.	Numeric amount for the allowance.
`multiplier_factor_numeric`	number	Optional	Percentage or multiplier used to calculate the allowance.	If sent, `base_amount` must also be sent.
`base_amount`	number	Optional	Base amount for the allowance.	If sent, `multiplier_factor_numeric` must also be sent.

Attachment object (request)

Use these fields when sending attachments on create or update requests.

Field	Type	Required	Description	Validation
`file_name`	string	Required	Name of the attached file, including extension.	Must be non-blank.
`file_type`	string	Required	MIME type of the attachment.	Must be one of: `text/csv`, `application/pdf`, `image/png`, `image/jpeg`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `application/vnd.oasis.opendocument.spreadsheet`.
`file_content`	string	Required	Base64-encoded file bytes.	Must be valid Base64. Leading and trailing whitespace is trimmed before decode.

Attachment object (response)

Each element of attachments in document JSON responses (create, retrieve, list) includes metadata only. File bytes are not returned; use the Download attachment endpoint with attachments[].id.

Field	Type	Required	Description
`id`	string	Required	Unique attachment identifier. Use as `{attachmentId}` on the download endpoint.
`file_name`	string	Required	Stored file name.
`file_type`	string	Required	Stored MIME type.

file_content is request-only and is never included in responses.

Payment means array

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

Field	Type	Required	Description	Validation
`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.
`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`.
`id`	string	Optional	Payment means identifier.	Optional identifier for the payment instruction.
`payment_id`	array of strings	Optional	Payment reference identifiers.	Used for payment reconciliation.

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 section for details.
`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 section for details.
`calculation_rate`	number	Required	Exchange rate for tax calculation.	Must be a positive numeric rate.

Response meta_info object

The meta_info field is an object with the following attributes:

Field	Type	Required	Description	Validation
`peppol_status`	object	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:

Field	Type	Required	Description	Validation
`participant_status`	string	Optional	Participant-level processing status.	Must be one of the status values listed below.
`fta_status`	string	Optional	FTA submission/processing status.	Must be one of the status values listed below.
`overall_status`	string	Optional	Overall Peppol processing status.	Must be one of the status values listed below.
`validation_results`	array	Optional	Validation details/errors returned during processing.	Response-only list; empty when there are no validation issues.

Status values

Value	Meaning
`VALIDATION_FAILED`	The received document failed validation checks.
`PENDING`	Processing is in progress.
`APPROVED`	The document is accepted.
`REJECTED`	The document is processed but rejected.

Client processing guidance:

Treat overall_status as the primary state for workflow decisions.
Use participant_status and fta_status as stage-specific diagnostics for UI and support logs.
If overall_status is PENDING, keep the invoice in a processing state and poll/re-fetch later.
If overall_status is APPROVED, mark the Peppol flow as successful and continue normal downstream actions.
If overall_status is REJECTED or VALIDATION_FAILED, stop submission-dependent actions and surface the failure to users.
When validation_results is not empty, display user-friendly error summaries from text, and retain flag, reasonCode, location, and test for troubleshooting.
participant_status or fta_status can be null in early/failed validation stages; do not treat null alone as success or failure.

Invoice type codes (380 and 480)

Choose invoice_type_code based on whether the business profile identified by {profileId} is VAT registered.

Code	Name	When to use	Line-item rule
`380`	Commercial / tax invoice	Use when the business profile is VAT registered and the supply is a standard taxable supply.	At least one line must use a standard-rate category (`S`, `AE`, etc.)—not only `E`, `O`, `Z`, or `N` (Peppol `IBR-151-AE`).
`480`	Invoice out of scope of tax	Use when the business profile is not VAT registered or the supply is otherwise outside UAE VAT scope.	Lines, charges, and allowances must use `E`, `Z`, or `O` only (Peppol `IBR-122-AE`). See Invoice out of scope (type code 480) section for details.

Non-AED invoices

When document_currency_code is not AED, the following rules apply (enforced at API validation):

Rule	Detail
`tax_currency_code`	Required; must be `AED`.
`tax_currency_code` vs `document_currency_code`	Must differ.
`tax_exchange_rate`	Required; `source_currency_code` must match `document_currency_code`; `target_currency_code` must match `tax_currency_code`.
Calculated fields	`tax_amount_in_aed` and `payable_amount_in_aed` are derived using the exchange rate.

Example exchange rate block for a USD invoice:

"document_currency_code": "USD",
"tax_currency_code": "AED",
"tax_exchange_rate": {
  "source_currency_code": "USD",
  "target_currency_code": "AED",
  "calculation_rate": 3.6725
}

See Non-AED invoice example section for details.

Invoice out of scope (type code 480)

Use invoice_type_code 480 when the supplier business profile is not liable for VAT or the supply falls outside UAE VAT scope.

Rule	Detail
Tax categories	Line, charge, and allowance tax categories must be `E`, `Z`, or `O` only—not `S`, `AE`, or `N`.
VAT registration	If your profile is not VAT registered, use `480` for your supplies instead of `380`.
Profile flags	Cannot combine `480` with Summary invoice, Deemed supply, or Profit Margin Scheme flags (Peppol `IBR-157-AE`).
Reversal	You are not required to change back to type `380` if your VAT registration status changes later—issue new invoices with the correct type going forward.

See Out of scope invoice section for details.

Tax point date (UAE VAT)

tax_point_date (UBL IBT-007) is the date when VAT liability arises per UAE VAT Law.

Topic	Detail
API behavior	Optional on create. When omitted, the field is stored as `null` and omitted from generated UBL XML.
When provided	Format `yyyy-MM-dd`; must be on or before `issue_date` (Peppol `IBR-141-AE`).
Regulatory fallback	When omitted, tax authorities may derive the VAT point date using scenario-specific rules. The fallback sequence depends on invoice type and profile flags—for example Summary invoice, Export, `invoice_period` dates, and `delivery.actual_delivery_date`. Confirm the exact sequence with your compliance team or internal VAT specification.
Recommendation	Send `tax_point_date` explicitly when you know the supply date to avoid ambiguity at Peppol/FTA validation.

Profile execution ID

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

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.

Free Trade Zone (FTZ) — position 1 (`1XXXXXXX`)

Supply of goods or services in a Free Trade Zone (FTZ).

When this flag is 1, set buyer_customer_party.id to a valid Beneficiary TIN. See Buyer customer party object section for details. Example: Free Trade Zone.

Deemed supply — position 2 (`X1XXXXXX`)

Supply of goods or services without consideration.

When this flag is 1, payment_means may be omitted. The buyer must be a UAE party (accounting_customer_party.postal_address.country_code = AE); non-UAE B2B buyers are rejected. For cross-border supplies, use Exports instead. Example: Deemed supply.

Profit Margin Scheme — position 3 (`XX1XXXXX`)

Supply of goods under the profit margin scheme.

No additional mandatory fields beyond standard validation. Example: Profit margin scheme.

Summary invoice — position 4 (`XXX1XXXX`)

Taxable person makes more than one supply to the same person in the same calendar month.

When this flag is 1, invoice_period is required (IBR-138-AE). Provide at least one of start_date or end_date (IBR-CO-19); description is optional. Example: Summary invoice.

Continuous Supply — position 5 (`XXXX1XXX`)

Supply of goods and/or services made on a recurrent basis.

No additional mandatory fields beyond standard validation. Example: Continuous supply.

Disclosed Agent Billing — position 6 (`XXXXX1XX`)

An agent who is a VAT registrant makes a supply on behalf of the principal.

When this flag is 1, set seller_supplier_party.id to a valid Principle ID TRN that differs from the seller VAT identifier on the business profile. Example: Disclosed agent billing.

Supply through e-commerce — position 7 (`XXXXXX1X`)

Supply of goods or services via e-commerce.

When this flag is 1, delivery with delivery_location.address is required. street_name, city_name, country_subentity, and country_code are mandatory. Example: E-commerce supply.

Exports — position 8 (`XXXXXXX1`)

Supply of goods or services outside the UAE.

When this flag is 1, delivery with delivery_location.address is required. street_name, city_name, country_subentity, and country_code are mandatory; country_code must not be AE. accounting_customer_party.party_tax_scheme is optional when the buyer is non-UAE. Example: 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`	Basic sale invoice
Out of scope (`480`)	`00000000` + `invoice_type_code` `480`	Out of scope invoice
Free Trade Zone (FTZ)	`10000000`	Free Trade Zone
Summary invoice	`00010000`	Summary invoice
Disclosed Agent Billing	`00000100`	Disclosed agent billing
Export delivery	`00000001`	Export transaction with delivery
Non-AED currency	`00000000`	Non-AED invoice

Implementation notes

Differences between documentation, API validation, and Peppol transmission rules:

Topic	API layer	Peppol / FTA (transmission)
`tax_point_date`	No default when omitted; omitted from XML	`IBR-141-AE` when present
`payment_means`	Required unless deemed-supply flag is `1`	Per PINT AE
Summary / agent / export profile flags	Partial enforcement at API	Full enforcement via schematron (`IBR-138-AE`, `IBR-137-AE`, etc.)
`480` / `380` tax categories	Not cross-checked at API	Enforced at transmission (`IBR-122-AE`, `IBR-151-AE`)
`accounting_supplier_party`	Always overwritten from `{profileId}`	Supplier from business profile

See Implementation notes for the full cross-document gap list.

Attachments

attachments carries document-level supporting files for the invoice—not line-level files on document_lines. Send each file as Base64-encoded binary inside the JSON body (not multipart upload, not a separate upload URL). The API stores attachments on the document and emits them in UBL as cac:AdditionalDocumentReference → cac:Attachment → cbc:EmbeddedDocumentBinaryObject. On create, omit attachments or send [].

Attachment object

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

Field	Type	Required	Description	Validation
`file_name`	string	Required	Original filename (UBL `filename` attribute). Example: `delivery_note.pdf`.	Must not be blank.
`file_type`	string	Required	MIME type (`mimeCode` in UBL).	Must be one of the allowed values in Allowed file_type values below.
`file_content`	string	Required	Standard Base64 of the raw file bytes (no `data:...;base64,` prefix).	Must be valid Base64; must not be blank.

API scope

Document	Create endpoint	`attachments` in request	8 MB body limit on create
Sales invoice	`POST /api/sales-invoices/{profileId}`	Yes	Yes
Purchase invoice	`POST /api/purchase-invoices/{profileId}`	Yes	Yes
Sales credit note	`POST /api/sales-credit-notes/{profileId}`	Yes	Yes
Purchase credit note	`POST /api/purchase-credit-notes/{profileId}`	Yes	Yes

GET responses return attachments in the same shape as the request.

Allowed `file_type` values

MIME type	Typical extension
`application/pdf`	`.pdf`
`image/png`	`.png`
`image/jpeg`	`.jpg`, `.jpeg`
`text/csv`	`.csv`
`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`	`.xlsx`
`application/vnd.oasis.opendocument.spreadsheet`	`.ods`

Any other value is rejected with a validation error such as *File type must be one of the allowed values*. Use image/jpeg for .jpg files—not image/jpg.

Validation rules

Rule	Behavior
`attachments` omitted or `null`	Allowed
Empty array `[]`	Allowed
Each item	Validated when present
`file_name` / `file_type` / `file_content` blank	Rejected
`file_content` not valid Base64	Rejected (File content must be valid base64)
Max count per document	No explicit count limit (only total payload size)

Field-level errors typically use paths such as attachments[0].file_type, attachments[0].file_content, etc.

Payload size

On create for the four invoice and credit-note POST endpoints above, the entire HTTP request body must be ≤ 8 MB. That limit includes all JSON—header, parties, lines, tax, and Base64 attachments (Base64 adds roughly 33% overhead). Over the limit, the API returns 413 with a message like *Payload size should not exceed 8MB*.

Compress PDFs, limit the number and size of files, and budget payload space: the server may append another PDF after validation (see below).

Server behavior on create

After validation, the service appends a system-generated PDF to any client-supplied attachments:

Document	Auto-added file
Sales / purchase invoice	`invoice.pdf`, `application/pdf`
Sales / purchase credit note	`credit-note.pdf`, `application/pdf`

The response attachments may therefore include your files plus the generated PDF. Do not rely on array order; identify files by file_name and file_type.

Client implementation guide

Read file bytes from disk or memory.
Base64-encode with the standard alphabet (no data:...;base64, prefix).
Set file_type to an exact MIME string from the allowlist above.
Set file_name with an extension that matches the content.
Build the full document JSON; measure serialized size if you are near 8 MB.
On success, parse attachments from the response; expect invoice.pdf or credit-note.pdf on invoice/credit-note create.
For display or download, decode file_content from Base64 client-side—GET responses return embedded content in the same shape.

Errors and HTTP status

Condition	Status	Example message / path
Body > 8 MB (create, four main doc types)	413	`errors.message`: Payload size should not exceed 8MB
Invalid MIME	400	`attachments[n].fileType`
Invalid Base64	400	`attachments[n].fileContent`
Missing file name	400	`attachments[n].fileName`

Best practices

Prefer PDF for supporting documents and keep files small.
Assume the invoice or credit-note PDF is always added on create—do not upload a duplicate unless you need it.
If integrations fail with 413, reduce attachment size or handle supporting documents outside this API—the API does not support chunked upload.
Store returned Base64 carefully; responses can be large.

Required data

Customer party objects — Complete accounting_customer_party with name, address, and tax scheme when required
Business profile identifier — Supplier business_profile_id in the path; 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

Rule	Description
Time fields	When sending `issue_time` or `delivery_time`, use Gulf Standard Time (GST, UTC+4). Format `HH:mm:ss`.
Profile execution ID	Must match pattern `^[0-1]{8}$`
Invoice Type Code	Must be `380` or `480`.
UAE addresses	Must include `country_subentity` (emirate code: DXB, AUH, SHJ, etc.)
Party VAT (`party_tax_scheme`)	Optional for UAE parties. If either `company_id` or `tax_scheme` is provided, both are required with UAE VAT format
VAT/TRN format	15 digits; starts with `1` and ends with `03`
Customer registration	Optional. If `scheme_agency_id` is provided, `company_id` is required and type-specific rules apply. See The Customer party object.
UAE business customer TIN	Required for UAE business customers. Exactly 10 characters, must start with `1`
Document number	Must be unique within organization (if provided)
Business profile ID	Must exist in your organization
Permissions	User must have permission to create invoices for the specified business profile

Response

Status code: 201 Created

Returns the created sales invoice with all request fields echoed plus system-generated and calculated fields.

Response body fields

Field	Type	Source	Description
`id`	string	System Provided	Primary identifier for the document (UUID). Automatically generated when the invoice is created.
`org_id`	string	System Provided	Unique identifier of the organization that owns this invoice.
`document_sequence`	long	System Provided	Sequential number for the invoice within your organization. Used for compliance and tracking.
`allowance_total_amount`	number	Calculated	Total of all document-level allowances.
`charge_total_amount`	number	Calculated	Total of all document-level charges.
`line_extension_amount`	number	Calculated	Sum of all line amounts before charges, allowances, and taxes. UBL 2.1 LineExtensionAmount.
`tax_exclusive_amount`	number	Calculated	Line extension plus charges minus allowances, before tax. UBL 2.1 TaxExclusiveAmount.
`tax_amount`	number	Calculated	Aggregated VAT amount in document currency. UBL 2.1 TaxTotal.
`tax_amount_in_aed`	number	Calculated	Total tax amount converted to AED.
`tax_inclusive_amount`	number	Calculated	Tax exclusive amount plus total tax. UBL 2.1 TaxInclusiveAmount.
`payable_amount`	number	Calculated	Final amount due. UBL 2.1 PayableAmount.
`payable_amount_in_aed`	number	Calculated	Final amount payable in AED.
`total_item_allowances`	number	Calculated	Total of all line-level allowances.
`total_item_charges`	number	Calculated	Total of all line-level charges.
`total_taxable_amount`	number	Calculated	Total taxable amount.
`total_non_taxable_amount`	number	Calculated	Total non-taxable amount.
`tax_breakdown`	array	Calculated	Tax amounts by tax category (S, Z, E, O, AE, N) and rate. UBL 2.1 TaxSubtotal.
`is_phase2_document`	boolean	System Provided	Whether the document is Peppol-enabled (Phase 2).
`meta_info`	object	System Provided	Additional metadata. See Meta info object below.

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

See the right panel for complete response JSON.

Error responses

Status	Description
400 Bad Request	Invalid request parameters or validation failed. For validation errors, the response includes field-specific errors.
401 Unauthorized	Authentication required or invalid token.
413 Request Entity Too Large	The request payload size exceeds the allowed limit of 8MB.
500 Internal Server Error	An error occurred while processing the request.

Request

# Base URL: https://api-sandbox.ae.marmin.ai
# POST /api/sales-invoices/{business_profile_id}

curl -X POST "https://api-sandbox.ae.marmin.ai/api/sales-invoices/MBP-1234567890" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-MARMIN-VERSION: 20260101" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_execution_id": "00000000",
    "issue_date": "2025-05-24",
    "issue_time": "10:30:00",
    "note": "Thank you for your business",
    "tax_point_date": "2025-04-24",
    "document_currency_code": "AED",
    "accounting_cost": "COST-001",
    "invoice_period": {
      "start_date": "2025-05-01",
      "end_date": "2025-05-31",
      "description": "Monthly"
    },
    "buyer_customer_party": { "id": "1001234567" },
    "seller_supplier_party": { "id": "100123456789003" },
    "delivery": {
      "actual_delivery_date": "2025-05-25",
      "delivery_location": {
        "id": "LOC-001",
        "address": {
          "street_name": "456 Delivery St",
          "city_name": "Abu Dhabi",
          "postal_zone": "54321",
          "country_subentity": "AUH",
          "country": "United Arab Emirates",
          "country_code": "AE"
        }
      }
    },
    "payment_terms": {
      "payment_means_id": "abc",
      "note": "Payment",
      "amount": 100.0,
      "installment_due_date": "2025-04-08"
    },
    "charges": [{
      "reason_code": "FC",
      "reason": "Freight charge",
      "amount": 50.0,
      "tax_category": { "id": "S", "percent": 5.0, "tax_scheme": "VAT" }
    }],
    "allowances": [{
      "reason_code": "95",
      "reason": "Discount",
      "amount": 10.0,
      "tax_category": { "id": "S", "percent": 5.0, "tax_scheme": "VAT" }
    }],
    "accounting_customer_party": {
      "endpoint_id": "<BUYER_PEPPOL_ID>",
      "endpoint_scheme_id": "0235",
      "party_name": "Marmin UAE - Shashank Sandbox Seller",
      "profile_id": "MBP-LEUYV0IANC",
      "postal_address": {
        "street_name": "Address",
        "additional_street_name": "Address",
        "city_name": "City",
        "postal_zone": "12312",
        "country_subentity": "DXB",
        "country": "United Arab Emirates",
        "country_code": "AE"
      },
      "party_tax_scheme": { "company_id": "100000000000003", "tax_scheme": "VAT" },
      "tin": "1000000001",
      "scheme_agency_id": "TL",
      "company_id": "1234567111",
      "authority_name": "Dubai Department of Economy and Tourism",
      "name": "Marmin UAE - Shashank Sandbox Seller",
      "email": "sr@marmin.ai",
      "telephone": "919632802392"
    },
    "invoice_type_code": "380",
    "due_date": "2025-06-24",
    "payment_means": [{
      "payment_means_code": "30",
      "payment_id": ["PAY-REF-001"],
      "payee_financial_account": { "id": "IBAN123", "name": "Account Name" }
    }],
    "prepaid_amount": 0.0,
    "payable_rounding_amount": 0.0,
    "document_lines": [{
      "quantity": 2.0,
      "unit_code": "EA",
      "order_line_reference": { "line_id": "LINE-001" },
      "description": "Product A description",
      "name": "Product A",
      "classified_tax_category": { "id": "S", "percent": 5.0, "tax_scheme": "VAT" },
      "price": { "base_amount": 100.0, "base_quantity": 1.0 }
    }],
    "attachments": [
        {
            "file_name": "supporting-document.pdf",
            "file_type": "application/pdf",
            "file_content": "<base64>"
        }
    ],
    "document_source": "API"
  }'

Response

{
    "accounting_cost": "COST-001",
    "accounting_customer_party": {
        "endpoint_id": "<BUYER_PEPPOL_ID>",
        "endpoint_scheme_id": "0235",
        "party_name": "Marmin UAE - Shashank Sandbox Seller",
        "profile_id": "MBP-LEUYV0IANC",
        "postal_address": {
            "street_name": "Address",
            "additional_street_name": "Address",
            "city_name": "City",
            "postal_zone": "12312",
            "country_subentity": "DXB",
            "address_line": null,
            "country": "United Arab Emirates",
            "country_code": "AE"
        },
        "party_tax_scheme": {
            "company_id": "100000000000003",
            "tax_scheme": "VAT"
        },
        "tin": "1000000001",
        "scheme_agency_id": "TL",
        "company_id": "1234567111",
        "authority_name": "Dubai Department of Economy and Tourism",
        "name": "Marmin UAE - Shashank Sandbox Seller",
        "email": "sr@marmin.ai",
        "telephone": "919632802392",
        "logo_url": null
    },
    "accounting_supplier_party": {
        "endpoint_id": "<SELLER_PEPPOL_ID>",
        "endpoint_scheme_id": "0235",
        "party_name": "MadMan",
        "profile_id": "MBP-TS1QWMZCK3",
        "postal_address": {
            "street_name": "Dubai kuruku sandu",
            "additional_street_name": "curve dungeon dubai",
            "city_name": "riyadh",
            "postal_zone": "232112",
            "country_subentity": "AUH",
            "address_line": "2112",
            "country": "United Arab Emirates",
            "country_code": "AE"
        },
        "party_tax_scheme": {
            "company_id": "186276396982103",
            "tax_scheme": "VAT"
        },
        "tin": "1318224273",
        "scheme_agency_id": "PAS",
        "company_id": "9762982708",
        "company_scheme_id": null,
        "authority_name": "",
        "passport_issuing_country_code": "AE",
        "company_legal_form": "",
        "name": "Hari Pradap V",
        "email": "hp@marmin.ai",
        "telephone": "78697639872",
        "logo_url": "https://res.cloudinary.com/marmin-seller-logo/image/upload/v1762512384/user_billing_logo/lgg4qlqngauh1oxgbmqu.png"
    },
    "allowance_total_amount": 10.0,
    "allowances": [
        {
            "reason_code": "95",
            "reason": "Discount",
            "amount": 10.0,
            "multiplier_factor_numeric": null,
            "base_amount": null,
            "tax_category": {
                "id": "S",
                "percent": 5.0,
                "tax_scheme": "VAT"
            }
        }
    ],
    "attachments": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "file_name": "supporting-document.pdf",
        "file_type": "application/pdf"
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "file_name": "invoice.pdf",
        "file_type": "application/pdf"
      }
    ],
    "billing_reference": [
        {
            "id": "INV-PRE-001",
            "issue_date": "2025-04-15"
        }
    ],
    "buyer_customer_party": {
        "id": "1001234567"
    },
    "buyer_reference": "BR-REF-001",
    "charge_total_amount": 50.0,
    "charges": [
        {
            "reason_code": "FC",
            "reason": "Freight charge",
            "amount": 50.0,
            "multiplier_factor_numeric": null,
            "base_amount": null,
            "tax_category": {
                "id": "S",
                "percent": 5.0,
                "tax_scheme": "VAT"
            }
        }
    ],
    "contract_document_reference": {
        "id": "CONTRACT-001",
        "document_description": "Master agreement"
    },
    "delivery": {
        "actual_delivery_date": "2025-05-25",
        "delivery_location": {
            "id": "LOC-001",
            "address": {
                "street_name": "456 Delivery St",
                "city_name": "Abu Dhabi",
                "postal_zone": "54321",
                "country_subentity": "AUH",
                "country": "United Arab Emirates",
                "country_code": "AE"
            }
        },
    },
    "despatch_document_reference": {
        "id": "DESP-001"
    },
    "document_currency_code": "AED",
    "document_lines": [
        {
            "quantity": 2.0,
            "unit_code": "EA",
            "order_line_reference": {
                "line_id": "LINE-001",
                "order_reference_id": null
            },
            "description": "Product A description",
            "name": "Product A",
            "classified_tax_category": {
                "id": "S",
                "percent": 5.0,
                "tax_scheme": "VAT"
            },
            "price": {
                "price_amount": 100.0,
                "base_quantity": 1.0,
                "allowance": {
                    "amount": 0.0,
                    "base_amount": 100.0,
                }
            },
            "net_amount": 200.0,
            "base_amount": 200.0,
            "total_amount": 210.0,
            "total_amount_in_aed": 210.0,
            "tax_amount": 10.0,
            "tax_amount_in_aed": 10.0
        }
    ],
    "document_number": "INV-12",
    "document_sequence": 12,
    "document_source": "API",
    "due_date": "2025-06-24",
    "id": "52c2e50b-a76c-4422-8a2d-1552bc0a207f",
    "invoice_period": {
        "start_date": "2025-05-01",
        "end_date": "2025-05-31",
        "description": "Monthly"
    },
    "invoice_type_code": "380",
    "is_phase2_document": true,
    "issue_date": "2025-05-24",
    "issue_time": "10:30",
    "line_extension_amount": 200.0,
    "meta_info": null,
    "note": "Thank you for your business",
    "order_reference": {
        "id": "ORD-001",
        "sales_order_id": "SO-001"
    },
    "org_id": "f7f8c445-c990-4683-9617-c66cc16a6ffd",
    "originator_document_reference": {
        "id": "ORIG-001"
    },
    "payable_amount": 252.0,
    "payable_amount_in_aed": 252.0,
    "payable_rounding_amount": 0.0,
    "payment_means": [{
        "payment_means_code": "30",
        "payment_id": [
            "PAY-REF-001"
        ],
        "payee_financial_account": {
            "id": "IBAN123",
            "name": "Account Name",
        },
    }],
    "payment_terms": {
        "payment_means_id": "abc",
        "note": "Payment",
        "amount": 100.0,
        "installment_due_date": "2025-04-08"
    },
    "prepaid_amount": 0.0,
    "profile_execution_id": "00000000",
    "project_reference": {
        "id": "PRJ-001"
    },
    "receipt_document_reference": {
        "id": "REC-001"
    },
    "seller_supplier_party": {
        "id": "100123456789003"
    },
    "statement_document_reference": {
        "id": "STMT-001"
    },
    "tax_amount": 12.0,
    "tax_amount_in_aed": 12.0,
    "tax_breakdown": [
        {
            "tax_category_code": "S",
            "tax_percentage": 5.0,
            "taxable_amount": 240.0,
            "tax_amount": 12.0
        }
    ],
    "tax_exclusive_amount": 240.0,
    "tax_inclusive_amount": 252.0,
    "tax_point_date": "2025-04-24",
    "total_item_allowances": 0.0,
    "total_item_charges": 0.0,
    "total_non_taxable_amount": 0.0,
    "total_taxable_amount": 240.0
}

Create a sales invoice

Rate limit

Path parameters

Request body

Request fields

Conditional field rules

Customer party object

Response party fields

Address object

Tax category object

Buyer customer party object

Seller supplier party object

Payee party object

Tax representative party object

Delivery object

Delivery location object

Order reference object

Billing reference object

Despatch document reference object

Receipt document reference object

Statement document reference object

Originator document reference object

Contract document reference object

Project reference object

Price object

Document line object

Invoice period object

Order line reference object

Despatch line reference object

Line document reference object

Buyer item identification object

Seller item identification object

Standard item identification object

Additional item identification object

Line item classification (UI to API)

Commodity classification object

Origin country object

Additional item property object

Charge object

Allowance object

Attachment object (request)

Attachment object (response)

Payment means array

Card account object

Payee financial account object

Payment mandate object

Payment terms object

Tax exchange rate object

Response meta_info object

Peppol status object

Status values

Client processing guidance:

Invoice type codes (380 and 480)

Non-AED invoices

Invoice out of scope (type code 480)

Tax point date (UAE VAT)

Profile execution ID

Free Trade Zone (FTZ) — position 1 (`1XXXXXXX`)

Deemed supply — position 2 (`X1XXXXXX`)

Profit Margin Scheme — position 3 (`XX1XXXXX`)

Summary invoice — position 4 (`XXX1XXXX`)

Continuous Supply — position 5 (`XXXX1XXX`)

Disclosed Agent Billing — position 6 (`XXXXX1XX`)

Supply through e-commerce — position 7 (`XXXXXX1X`)

Exports — position 8 (`XXXXXXX1`)

Related examples

Implementation notes

Attachments

Attachment object

API scope

Allowed `file_type` values

Validation rules

Payload size

Server behavior on create

Client implementation guide

Errors and HTTP status

Best practices

Required data

System behavior

Validation rules