API Docs

Create a Purchase Register Entry

Creates a document in the purchase register. Use entry_type PURCHASE or PURCHASE_ADJUSTMENT and document_type INVOICE or CREDIT_NOTE. Include org_id when your API requires it. A valid bearer token is required.

Rate limit

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

Path parameter

POST /api/document-registers/{profile_id}
Authorization: Bearer {jwt_token}
X-MARMIN-VERSION: 20260507

Parameter	Type	Required	Description
`profile_id`	string	Required	Business profile ID of the customer (your company). The API uses this to fill `accounting_customer_party`, so you do not send it in the request body.

Document register request – all fields

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

Do not send: accounting_customer_party — the API sets the customer from profile_id in the URL.

Field	Type	Required	Description
`issue_date`	string	Required	Date the document was issued. Format: `YYYY-MM-DD`.
`transaction_date`	string	Required	Date of the transaction. Format: `YYYY-MM-DD`.
`accounting_period`	string	Required	Accounting period for the entry. Format: `YYYY-MM`.
`document_number`	string	Required	Your unique document reference number.
`document_type`	string	Required	Type of document. One of: `INVOICE`, `CREDIT_NOTE`.
`entry_type`	string	Required	Type of register entry. For purchase use `PURCHASE` or `PURCHASE_ADJUSTMENT`.
`note`	string	Required	Free-text note or reason for the document.
`accounting_supplier_party`	object	Required	Supplier (vendor) party. Must include `tax_scheme` and `postal_address`. See Party table below.
`document_lines`	array	Required	Line items. At least one item required.
`document_currency_code`	string	Required	ISO currency code (e.g. `AED`). See Get Currency Names and Codes.
`payable_amount`	number	Required	Total amount payable including tax. Must be ≥ 0.
`tax_amount`	number	Required	Total tax amount. Must be ≥ 0.
`tax_exchange_rate`	object	Conditional	Exchange rate when `document_currency_code` is not `AED`. `target_currency_code` must be `AED`.

Non-AED register entries

When document_currency_code is not AED, include tax_exchange_rate with target_currency_code = AED.

Party (accounting_supplier_party / accounting_customer_party)

Field	Type	Required	Description
`name`	string	Optional	Legal or display name of the party.
`party_name`	string	Optional	Trading or business name of the party.
`tax_scheme`	string	Required	Tax scheme (for example `VAT` for UAE). See Get Tax Schemes.
`tin`	string	Optional	Tax identification number (TRN).
`email`	string	Optional	Party email address.
`telephone`	string	Optional	Party telephone number.
`gl_account`	string	Optional	GL account.
`postal_address`	object	Required	Party address. See Address object below.

Address object

Party postal_address uses the address object structure.

Field	Type	Required	Description
`street_name`	string	Required	Street name and number.
`additional_street_name`	string	Optional	Additional street details.
`city_name`	string	Required	City name.
`postal_zone`	string	Optional	Postal or ZIP code.
`country_subentity`	string	Required	Emirate or region code (e.g. `DXB`, `SHJ`, `AUH`). See Get UAE Subdivisions.
`address_line`	string	Optional	Additional address line.
`country`	string	Required	Country name (e.g. `United Arab Emirates`).
`country_code`	string	Required	ISO 3166-1 alpha-2 country code (e.g. `AE`). See Get Countries.

Document line (each item in `document_lines`)

Field	Type	Required	Description
`name`	string	Required	Line item description or product/service name.
`quantity`	number	Required	Quantity. Must be ≥ 1.
`net_amount`	number	Required	Net amount (before tax) for this line. Must be ≥ 0.
`tax_amount`	number	Required	Tax amount for this line. Must be ≥ 0.
`classified_tax_category`	object	Required	Tax category for this line. See Tax category object below.

Tax category object

Line-item classified_tax_category uses the shared tax category structure.

Field	Type	Required	Description
`id`	string	Required	Tax category code (for example `S`, `Z`, `E`). See Get Tax Categories.
`percent`	number	Optional	Tax rate as percentage (0–100). Should align with `id`.
`tax_exemption_reason_code`	string	Conditional	FTA exemption reason code. Required when `id` is `E`. See Get Tax Exemption Reason Codes.
`tax_exemption_reason`	string	Conditional	Exemption reason description. Required when `id` is `E`; must match the selected `tax_exemption_reason_code` description.
`tax_scheme`	string	Optional	Tax scheme (for example `VAT`). See Get Tax Schemes.

Supplier and customer from profile

For purchase and purchase adjustments:

Entry type	Party from profile	In request body
`PURCHASE`, `PURCHASE_ADJUSTMENT`	Customer (`accounting_customer_party`)	Do not send `accounting_customer_party`. Send `accounting_supplier_party`.

Use the same request body structure for all purchase scenarios; only entry_type and document_type change.

Request body

Send a JSON object with the fields described in the request fields below. Typical combinations:

Scenario	`entry_type`	`document_type`
Purchase invoice	`PURCHASE`	`INVOICE`
Purchase credit note	`PURCHASE`	`CREDIT_NOTE`
Purchase adjustment	`PURCHASE_ADJUSTMENT`	`INVOICE` or `CREDIT_NOTE`

Include org_id when your API requires it.

Response

Status code: 201 Created

Response body:

Returns the created register entry with request data and system‑generated fields (id, uuid, source_type, line ids, created_at, updated_at). When provided, org_id is included in the response.

Error responses

400 Bad Request

Invalid request body or validation failed. The response returns an errors object with field names as keys and error messages as values.

401 Unauthorized

Authentication required or invalid token.

500 Internal Server Error

An error occurred while processing the request.