API Docs

Document-level charges and allowances

Use this payload when charges or discounts apply to the credit note total rather than a specific line.

Contract reference

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

Core fields

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

Root-level fields used in this example.

Field	Type	Required	Description	Validation
`profile_execution_id`	string	Required	Credit note transaction type code.	Exactly 8 characters; each character `0` or `1` (binary flags). See Profile execution ID and Examples.
`issue_date`	string	Required	The date when the credit note was issued.	Format `yyyy-MM-dd`; must be a valid calendar date.
`issue_time`	string	Optional	The time when the credit note was issued.	If present, format `HH:mm:ss` (e.g. `10:30:00`).
`credit_note_type_code`	string	Required	The type of credit note.	For sales credit notes this code must be `381` or `81.
`discrepancy_response`	string	Required	Reason for issuing the credit note per UAE FTA DL8.61.1.	Must be one of the allowed discrepancy codes (e.g. `DL8.61.1.A`, `DL8.61.1.B`, `DL8.61.1.C`, `DL8.61.1.D`, `DL8.61.1.E`, `VD`).
`document_currency_code`	string	Required	ISO 4217 alpha-3 currency code for all monetary amounts (e.g. `AED`).	Must be a valid ISO 4217 currency (e.g. `AED`). See Get Currency Names and Codes section for details.
`billing_reference`	array	Optional	Billing references, typically including the original invoice being credited.	For API sales credit notes, at least one reference to the original invoice is effectively mandatory; each item requires `id` and optional `issue_date` in `yyyy-MM-dd`.
`accounting_customer_party`	object	Required	The customer party receiving the credit note. See Party object below.	Must be a valid Party object; required in create requests.
`charges`	array	Optional	Document-level charges that adjust the amount (e.g. freight charge adjustment). See Charge object below.	If present: each charge must have a valid reason and amount/rate; tax category rules apply.
`allowances`	array	Optional	Document-level discounts/allowances (e.g. discount on returned items). See Allowance object below.	If present: each allowance must have a valid reason and amount/rate; tax category rules apply.
`document_lines`	array	Required	Credit note line items. See Document line object below.	Must contain at least one line; each line must satisfy the Document line object validation rules.
`document_source`	string	—	Indicates the origin of the e-invoice document. This identifies the specific external system, ERP, or platform that generated or transmitted the record. Examples: `SAP_S4HANA`, `Oracle_NetSuite`, `Internal_Portal`.	Optional. Accepts a string value. If not provided, the system assigns `API` as the default source.

Party object

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

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

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

Address object

Postal and delivery addresses use the shared address object structure.

Field	Type	Required	Description	Validation
`street_name`	string	Required	Street name or primary address line (UBL address line 1).	Must not be blank.
`additional_street_name`	string	Optional	Additional street name or address line 2.	Free text when provided.
`city_name`	string	Required	City or town name.	Must not be blank.
`postal_zone`	string	Optional	Postal or ZIP code.	Free text when provided.
`country_subentity`	string	Required	Country subdivision—emirate, state, or region code.	Must not be blank. When `country_code` is `AE`, use an approved emirate code from Get UAE Subdivisions.
`address_line`	string	Optional	Additional unstructured address line.	Free text when provided.
`country`	string	Required	Country name (e.g. `United Arab Emirates`).	Must not be blank.
`country_code`	string	Required	ISO 3166-1 alpha-2 country code (e.g. `AE`).	Must not be blank. See Get Countries section for details.

Price object

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

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

Tax category object

Tax categories share the same structure on line items (classified_tax_category), document-level charges[].tax_category, and allowances[].tax_category.

Field	Type	Required	Description	Validation
`id`	string	Required	Tax category code (UBL classified tax category ID).	Must not be blank. Valid codes include `S`, `Z`, `E`, `O`, `AE`, `N`. See Get Tax Categories section for details.
`percent`	number	Optional	VAT rate as a percentage (e.g. `5` for 5%).	Should align with the selected `id`.
`tax_exemption_reason_code`	string	Conditional	FTA tax exemption reason code.	Required when `id` is `E` (exempt). See Get Tax Exemption Reason Codes section for details.
`tax_exemption_reason`	string	Conditional	Tax exemption reason description.	Required when `id` is `E` (exempt). Must match the selected `tax_exemption_reason_code` description.
`tax_scheme`	string	Optional	Tax scheme identifier (typically `VAT` for UAE).	See Get Tax Schemes section for details.

Document line object

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

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

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

Payment means array

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

Field	Type	Required	Description	Validation
`id`	string	Optional	Payment means identifier.	Optional identifier for the payment instruction.
`payment_means_code`	string	Required	Payment means code (e.g. `54` for credit card).	Required when a `payment_means` item is sent. Must not be blank. Must be one of: `1`, `10`, `20`, `21`, `30`, `49`, `54`, `55`, `68`. See Get Payment Means Modes section for details.
`payment_id`	array of strings	Optional	Payment reference identifiers.	Used for payment reconciliation.
`card_account`	object	Conditional	Card account details.	Mandatory when `payment_means_code` is `54` or `55`.
`payee_financial_account`	object	Conditional	Payee bank/financial account details.	Mandatory when `payment_means_code` is `30`.
`payment_mandate`	object	Conditional	Payment mandate details.	Mandatory when `payment_means_code` is `49`.

Card account object

The card_account field is an object with the following attributes:

Field	Type	Required	Description	Validation
`primary_account_number_id`	string	Required	Primary account number identifier. UI label: PAN.	Mandatory when `payment_means_code` is `54` or `55`; must not be blank.
`network_id`	string	Required	Card network identifier. UI label: Network ID.	Mandatory when `payment_means_code` is `54` or `55`; must not be blank.
`holder_name`	string	Optional	Card holder name.	Free text.

Payee financial account object

The payee_financial_account field is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Optional	Payee financial account identifier. UI label: Payment account identifier.	Mandatory when `payment_means_code` is `30`.
`name`	string	Optional	Payee financial account name.	Free text.
`financial_institution_branch_id`	string	Optional	Financial institution branch identifier.	Free text.
`address`	object	Optional	Payee financial account address.	If present, see Address object.

Payment mandate object

The payment_mandate field is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Optional	Payment mandate identifier. UI label: Mandate reference Identifier.	Mandatory when `payment_means_code` is `49`.
`payer_financial_account_id`	string	Optional	Payer financial account identifier. UI label: Payer Financial Account Identifier.	Mandatory when `payment_means_code` is `49`.

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

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

See the example payload in the right-side panel.