API Docs

The credit note object

See the right panel for the complete object definition and code examples.

Attributes

Core fields

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

Field	Type	Required	Source	Description	Validation
`id`	string	Required	System-generated	Primary identifier for the document (UUID). Automatically generated when the document is created.	Response-only; not accepted in requests.
`org_id`	string	Required	System-generated	Unique identifier of the organization that owns this credit note.	Set by backend from your organization; not part of the create request body.
`profile_execution_id`	string	Required	Client-provided	Credit note transaction type code.	Exactly 8 characters; each character `0` or `1` (binary flags). See Profile execution ID and Examples.
`document_number`	string	Optional	Conditional (client-provided or system-generated)	The credit note number as displayed on the document.	Required for API-created credit notes; must be unique within the organization when provided.
`document_sequence`	number	Optional	System-generated	Sequential number for the credit note within your organization. Used for compliance and tracking.	Server-calculated sequence; do not send in create requests.
`issue_date`	string	Required	Client-provided	The date when the credit note was issued.	Format `yyyy-MM-dd`; must be a valid calendar date.
`issue_time`	string	Optional	Client-provided	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	Client-provided	The type of credit note.	For sales credit notes this code must be `381` or `81.
`discrepancy_response`	string	Required	Client-provided	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`).
`reason`	string	Optional	Client-provided	Free-text explanation or additional reason for the credit note.	Free text; often correlates with `discrepancy_response`.
`note`	string	Optional	Client-provided	Additional notes or terms displayed on the credit note.	Free text.
`tax_point_date`	string	Optional	Conditional (client-provided or system-generated default)	Tax point date per UAE VAT Law—when VAT liability arises.	If present: format `yyyy-MM-dd`; defaults to `issue_date` if omitted.
`document_currency_code`	string	Required	Client-provided	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.
`tax_currency_code`	string	Optional	Client-provided	ISO 4217 currency code for tax when it differs from document currency.	If present: valid ISO 4217 code; consistent with `document_currency_code` and requires `tax_exchange_rate` when different. See Get Currency Names and Codes.
`accounting_cost`	string	Optional	Client-provided	Accounting cost center / project cost identifier (if applicable).	Free text.
`buyer_reference`	string	Optional	Client-provided	Buyer reference (customer reference) for the credit note.	Free text.
`invoice_period`	object	Optional	Client-provided	Period covered by the credited supply (start_date, end_date, description).	If present: `start_date` and `end_date` must be `yyyy-MM-dd`, with `start_date` ≤ `end_date`.
`order_reference`	object	Optional	Client-provided	Reference to the original order. See Order reference object below.	If present: `id` must be provided; `issue_date` as `yyyy-MM-dd` when used.
`billing_reference`	array	Optional	Client-provided	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`.
`despatch_document_reference`	object	Optional	Client-provided	Reference to despatch/delivery document. See Despatch document reference object below.	If present: `id` required; `issue_date` `yyyy-MM-dd` when provided.
`receipt_document_reference`	object	Optional	Client-provided	Reference to receipt document. See Receipt document reference object below.	If present: `id` required; `issue_date` `yyyy-MM-dd` when provided.
`statement_document_reference`	object	Optional	Client-provided	Reference to statement document.	If present: `id` required; `issue_date` `yyyy-MM-dd` when provided.
`originator_document_reference`	object	Optional	Client-provided	Reference to originating document (when applicable).	If present: `id` required; `issue_date` `yyyy-MM-dd` when provided.
`contract_document_reference`	object	Optional	Client-provided	Reference to contract. See Contract document reference object below.	If present: `id` required; `issue_date` `yyyy-MM-dd` when provided.
`accounting_supplier_party`	object	Required	Conditional (usually system-generated from profile)	The supplier party issuing the credit note. See Party object below.	Typically derived from the supplier profile for sales credit notes; if sent, must be a valid Party.
`accounting_customer_party`	object	Required	Client-provided	The customer party receiving the credit note. See Party object below.	Must be a valid Party object; required in create requests.
`buyer_customer_party`	object	Optional	Client-provided	UAE e-invoicing field for Beneficiary ID (UBL `BTAE-01`). This is not a full party object. See Buyer customer party object below.	Required when Free Trade Zone applies (`profile_execution_id` first character is `1`); `id` must be a valid Beneficiary ID (TIN).
`seller_supplier_party`	object	Optional	Client-provided	UAE e-invoicing field for Principle ID (UBL `BTAE-14`). This is not a full party object. See Seller supplier party object below.	Required when Disclosed Agent Billing applies (`profile_execution_id` sixth character is `1`); `id` must be a valid Principle ID TRN and must differ from `accounting_supplier_party.party_tax_scheme.company_id`.
`payee_party`	object	Optional	Client-provided	The party to whom payment/refund should be made, if different from the supplier. See Payee party object below.	If present, must be a valid Payee party object.
`tax_representative_party`	object	Optional	Client-provided	Party authorized to represent the supplier for tax purposes. See Tax representative party object below.	If present, must be a valid Party (correct tax scheme and address).
`delivery`	object	Optional	Client-provided	Where and when the goods or services related to the credit note were delivered. See Delivery object below.	If present: `delivery_location` and `address` must be populated; may be mandatory for exports.
`payment_terms`	object	Optional	Client-provided	Payment terms and conditions associated with the credit note. See Payment terms object below.	If present: date fields (e.g. `installment_due_date`, `due_date`) must be `yyyy-MM-dd`.
`charges`	array	Optional	Client-provided	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	Client-provided	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.
`tax_exchange_rate`	object	Optional	Client-provided	Exchange rate when tax currency differs from document currency. See Tax exchange rate object below.	Required when `tax_currency_code` differs from `document_currency_code`; must include `source_currency_code`, `target_currency_code`, and `calculation_rate`.
`prepaid_amount`	number	—	Client-provided	Total prepaid amount applied to the credit note.	Optional numeric; typically non-negative.
`payable_rounding_amount`	number	—	Client-provided	Rounding adjustment applied to payable amount.	Optional numeric; may be positive or negative depending on rounding direction.
`tax_breakdown`	array	—	Calculated	Tax amounts grouped by tax category and rate.	Response-only, generated from per-line tax categories.
`allowance_total_amount`	number	—	Calculated	Total of all document-level allowances.	Response-only, calculated from document-level allowances.
`charge_total_amount`	number	—	Calculated	Total of all document-level charges.	Response-only, calculated from document-level charges.
`line_extension_amount`	number	—	Calculated	Sum of all line amounts before charges, allowances, and taxes. UBL 2.1 LineExtensionAmount.	Response-only, derived from line net amounts.
`tax_exclusive_amount`	number	—	Calculated	Line extension plus charges minus allowances, before tax. UBL 2.1 TaxExclusiveAmount.	Response-only, calculated.
`tax_amount`	number	—	Calculated	Aggregated VAT amount in document currency. UBL 2.1 TaxTotal.	Response-only, calculated from tax breakdown.
`tax_amount_in_aed`	number	—	Calculated	Total tax amount converted to AED.	Response-only, calculated using tax exchange rate (if applicable).
`tax_inclusive_amount`	number	—	Calculated	Tax exclusive amount plus total tax. UBL 2.1 TaxInclusiveAmount.	Response-only, calculated.
`payable_amount`	number	—	Calculated	Final amount to be refunded/credited. UBL 2.1 PayableAmount.	Response-only, calculated as tax inclusive minus prepayments/rounding.
`payable_amount_in_aed`	number	—	Calculated	Final amount payable in AED.	Response-only, calculated using exchange rates.
`total_item_allowances`	number	—	Calculated	Total of all line-level allowances.	Response-only, sum over line-level allowances.
`total_item_charges`	number	—	Calculated	Total of all line-level charges.	Response-only, sum over line-level charges.
`total_taxable_amount`	number	—	Calculated	Total taxable amount for the credit note.	Response-only, derived from taxable lines and charges/allowances.
`total_non_taxable_amount`	number	—	Calculated	Total non-taxable amount.	Response-only, derived from non-taxable lines.
`document_lines`	array	Required	Client-provided	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	—	System-generated	Source of the credit note: `API`, `BULK_UPLOAD`, `PEPPOL`, or `UI`.	For this endpoint, value will always be `API` in requests and responses.
`meta_info`	object	Optional	System-generated	Additional metadata (timestamps, Peppol status, etc.). See Meta info object below.	Response-only metadata.
`is_phase2_document`	boolean	—	System-generated	Whether the document is Peppol-enabled (Phase 2).	Response-only flag; controlled by backend/Peppol integration.

For convenience, the shared nested object structures are documented below.

Party object

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

Field	Type	Required	Description	Validation
`name`	string	Required	Party name or display name.	Must be non-empty text.
`party_name`	string	Required	Legal name of the party.	Must be non-empty text.
`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.	Required; must satisfy address object validation.
`scheme_agency_id`	string	Optional	Scheme agency identifier.	If present, must be one of `TL`, `EID`, `PAS`, `CD`, `OTH`. See Get Registration Types.
`company_id`	string	Optional	Company or registration number.	Free-form registration number; may be validated per jurisdiction.
`party_tax_scheme`	object	Conditional	Tax scheme with TRN. Contains `company_id`, `tax_scheme`.	Required for UAE parties (`postal_address.country_code` is `AE`). Optional for non-UAE `accounting_customer_party` on export transactions (`profile_execution_id` seventh character is `1`). If present, must include a valid TRN or tax identifier and `tax_scheme` (usually `VAT`). See Get Tax Schemes.
`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.	If present, must be a valid Peppol scheme id. See Get Electronic Address Schemes.
`email`	string	Optional	Party email address.	Free text when provided.
`telephone`	string	Optional	Party telephone number.	Free text when provided.

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.

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.
`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.
`tax_exemption_reason`	string	Optional	Tax exemption reason description.	Free text when provided; often used with `tax_exemption_reason_code`.
`tax_scheme`	string	Optional	Tax scheme identifier (typically `VAT` for UAE).	See Get Tax Schemes.

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 when Free Trade Zone applies (`profile_execution_id` first character is `1`). 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 when Disclosed Agent Billing applies (`profile_execution_id` sixth character is `1`). Must be a valid TRN; must differ from the seller VAT identifier (`accounting_supplier_party.party_tax_scheme.company_id`).

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:

Field	Type	Required	Description	Validation
`delivery_location`	object	Optional	Location where goods or services are delivered.	If present, must include an `address` with valid address fields; required for exports.
`delivery_date`	string	Optional	Date of delivery.	If present, format `yyyy-MM-dd`.
`delivery_time`	string	Optional	Time of delivery.	If present, format `HH:mm:ss`.
`actual_delivery_date`	string	Optional	Actual date of delivery.	If present, format `yyyy-MM-dd`.

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	Description	Validation
`base_amount`	number	Required	Item net price.	Must not be negative.
`base_quantity`	number	Required	Item price base quantity.	Must be positive.
`allowance.amount`	number	Optional	Price level discount.	Must not be negative when provided.

Document line object

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

Field	Type	Required	Description	Validation
`name`	string	Required	Line item name.	Must be non-empty.
`description`	string	Optional	Line item description.	Free text.
`unit_code`	string	Required	Unit of measure. Contains `code` (e.g. `EA`), `desc`.	Must contain a valid UN/CEFACT unit code (e.g. `EA`, `KGM`, `LTR`). See Get Unit of Measure Codes.
`quantity`	number	Required	Quantity.	Must be a positive number.
`price`	object	Required	Line item price. See Price object.	Must satisfy Price object validation.
`base_amount`	number	Optional	Calculated base amount.	Response-only; calculated as quantity × price.
`net_amount`	number	Optional	Net amount.	Response-only; calculated.
`total_amount`	number	Optional	Total including tax.	Response-only; calculated.
`tax_amount`	number	Optional	Tax amount for the line.	Response-only; calculated from line tax.
`classified_tax_category`	object	Required	Line-item tax category. See Tax category object.	Must satisfy Tax category object validation; `tax_exemption_reason_code` is required when `id` is `E`.

Charge object

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

Field	Type	Required	Description	Validation
`charge_reason_code`	string	Required	UN/ECE Recommendation 20 charge reason code.	Must be a valid UN/ECE charge reason code (e.g. `FC`). See Get Charge Reason Codes.
`amount`	number	Required	Charge amount.	Must be numeric, usually ≥ 0.
`base_amount`	number	Optional	Base amount for the charge.	If used with percentages, must be provided consistently with multiplier/factor logic in your profile.
`tax_category`	object	Optional	Tax category applied to the charge.	If present, see Tax category object. `tax_exemption_reason_code` 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 reason.	At least one of `reason` or `reason_code` must be provided. Free text when 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.
`amount`	number	Required	Allowance amount.	Must be numeric, usually ≥ 0.
`base_amount`	number	Optional	Base amount for the allowance.	If used with percentages, must be provided consistently with multiplier/factor logic in your profile.
`tax_category`	object	Optional	Tax category for allowance adjustment.	If present, see Tax category object. `tax_exemption_reason_code` required when `id` is `E`.

Payment means object

The payment_means field 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).	Must be one of: `1`, `10`, `20`, `21`, `30`, `49`, `54`, `55`, `68`.
`payment_id`	string	Optional	Payment reference or identifier.	Free text; may be used for reconciliation.
`card_account`	object	Optional	Card details. Contains `primary_account_number_id`, `network_id`.	Required when `payment_means_code` is `54` or `55`; must include valid masked PAN and network id.
`financial_account`	object	Optional	Bank/financial account details.	Required for credit transfer scenarios (`payment_means_code` `30`).

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

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 credit note 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.