API Docs

The Customer party object

When you create a sales invoice, sales credit note, or proforma invoice, you include the buyer's details in the accounting_customer_party object. The fields and rules on this page describe that customer party and what you must send for Marmin to accept your request.

Customer rules are not the same as business profile or supplier rules.

Before you start

Decide whether the customer is a business or an individual. On sale documents, Marmin infers this from scheme_agency_id: EID or PAS means individual; all other values (or omission) mean business.
Check whether the customer's address is in the UAE (country_code = AE) or outside the UAE.
Registration details are optional. You do not need to send scheme_agency_id, company_id, authority_name, or passport_issuing_country_code unless you want to include them.
Keep registration and VAT separate:
Registration number (company_id) — trade license, cabinet decision, Emirates ID, passport number, or other identifier (only when you send registration details)
VAT number / TRN (party_tax_scheme.company_id) — 15-digit UAE tax registration number

Attributes

Core fields

Field	Type	Required	Description
`name`	string	Required	Display name for the customer.
`email`	string	Required	Customer email address.
`party_name`	string	Conditional	Legal name of the business. Required for business customers. Do not send for individuals.
`party_name_in_local_language`	string	Optional	Customer name in Arabic or local language.
`scheme_agency_id`	string	Optional	How the customer is registered, if you choose to include registration details. See Get Registration Types.
`company_id`	string	Optional	Official registration or identity number. Not the VAT/TRN. Only send when you include registration details — see If you include registration details below.
`authority_name`	string	Optional	Issuing authority for the trade license. Only relevant when `scheme_agency_id` is `TL`.
`passport_issuing_country_code`	string	Optional	Country that issued the passport. Only relevant when `scheme_agency_id` is `PAS`.
`tin`	string	Conditional	Taxpayer Identification Number (TIN) from EmaraTax. Required for UAE business customers. Must be 10 characters and start with `1`. Do not send for non-UAE business customers or individuals.
`party_tax_scheme`	object	Optional	VAT details for UAE business customers. If you send any part of it, you must send both fields in Party tax scheme object. Do not send for non-UAE business customers or individuals.
`endpoint_id`	string	Optional	Peppol electronic address for the customer.
`endpoint_scheme_id`	string	Optional	Scheme for `endpoint_id` (typically `0235`). See Get Electronic Address Schemes.
`telephone`	string	Optional	Customer telephone number.
`postal_address`	object	Required	Customer address. See Address object below.

Address object

Field	Type	Required	Description
`street_name`	string	Required	Street name or primary address line.
`additional_street_name`	string	Optional	Additional street details.
`city_name`	string	Required	City or town.
`postal_zone`	string	Optional	Postal or ZIP code.
`country_subentity`	string	Required	Emirate, state, or region code (e.g. `DXB`). For UAE addresses, use a code from Get UAE Subdivisions.
`address_line`	string	Optional	Additional address line.
`country`	string	Required	Country name (e.g. `United Arab Emirates`).
`country_code`	string	Required	Two-letter country code (e.g. `AE`). See Get Countries.

Party tax scheme object

Use this object only when you want to include the customer's UAE VAT registration (TRN).

Field	Type	Required	Description
`company_id`	string	Conditional	UAE VAT registration number (TRN). 15 digits only; must start with `1` and end with `01` or `03`. Required if you include `party_tax_scheme`.
`tax_scheme`	string	Conditional	Tax scheme, usually `VAT`. Required if you include `party_tax_scheme`. See Get Tax Schemes.

If you omit party_tax_scheme entirely, the request is valid. If you include either company_id or tax_scheme, you must include both, and the TRN must match the UAE format above.

Validation by scenario

UAE business customer

What to send	Rule
`name`, `email`, `postal_address`	Required
`party_name`	Required
`tin`	Required — 10 characters, starts with `1`
`scheme_agency_id`, `company_id`, `authority_name`	Optional — registration details are not required
`party_tax_scheme`	Optional; if sent, both TRN and `tax_scheme` required with valid TRN format
`passport_issuing_country_code`	Do not send

Non-UAE business customer

What to send	Rule
`name`, `email`, `party_name`, `postal_address`	Required
`scheme_agency_id`	Optional; `OTH` is typical
`company_id`	Optional; only send with `scheme_agency_id`
`tin`	Do not send
`party_tax_scheme`	Do not send

UAE individual customer

What to send	Rule
`name`, `email`, `postal_address`	Required
`scheme_agency_id`	Optional; if sent, must be `EID` or `PAS`
`party_name`	Do not send
`authority_name`	Do not send
`tin`, `party_tax_scheme`	Do not send
`passport_issuing_country_code`	Required when `scheme_agency_id` is `PAS`

If you include registration details

Registration fields are optional. If you choose to send scheme_agency_id, the following rules apply:

Registration type (`scheme_agency_id`)	Additional fields when registration is included
Any	`company_id` is required when `scheme_agency_id` is sent
`TL` (Trade License)	`authority_name` is also required
`PAS` (Passport)	`passport_issuing_country_code` is also required for UAE addresses
Business customer (UAE)	`TL` or `CD` are typical
Business customer (non-UAE)	`OTH` is typical
Individual customer	`EID` or `PAS`

See Get Registration Types.

Using this object on sale documents

Include these fields on accounting_customer_party when you create or resubmit a sales invoice or sales credit note. The same rules apply on proforma invoices for the customer party.

For export transactions (profile_execution_id seventh character is 1), VAT details on a non-UAE buyer may be omitted.