API Docs

The purchase credit note object

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

Attributes

Core fields

All root-level attributes on the purchase 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.
`transaction_type`	string	Required	Client-provided	Credit note transaction type code.	Exactly 20 characters; each character `1` or `X` (bitmap) as per Transaction type rules.
`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.
`status`	string	—	System-generated	Document lifecycle status. See Document status below.	Response-only. One of `ACTIVE` or `OBSOLETE`. Defaults to `ACTIVE` on create.
`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 purchase credit notes this code must be `261` (Self-billed Credit Note).
`discrepancy_response`	string	Required	Client-provided	Reason for issuing the credit note per OMN Tax Authority CL-02-OM	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 OMN 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. `OMR`).	Must be a valid ISO 4217 currency (e.g. `OMR`).
`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.
`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 purchase 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 purchase 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	Additional buyer party if different from accounting customer. See Party object below.	If present, must be a valid Party; may be validated against profile.
`seller_supplier_party`	object	Optional	Client-provided	Additional seller party if different from accounting supplier. See Party object below.	If present, must be a valid Party.
`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_means`	array	Optional	Client-provided	Payment method(s). See Payment means below.	Optional `0..n`. Code `30` requires `payee_financial_account`; `54`/`55` require `card_account`; `49` requires `payment_mandate`.
`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_omr`	number	—	Calculated	Total tax amount converted to OMR.	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_omr`	number	—	Calculated	Final amount payable in OMR.	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.
`seller_uuid`	string	Optional	Client-provided or system-generated	Seller identity UUID (BTOM-004). Auto-generated if omitted. See Invoice QR Code and Seller UUID.	Valid UUID format.
`qr_code_base64`	string	Optional	Client-provided or System-generated	Base64-encoded PNG QR code per Oman SRA v1.0.2. See Invoice QR Code and Seller UUID.	Valid Base64 format.
`uuid`	string	—	System-generated	Peppol network document identifier (distinct from `id` and `seller_uuid`).	Response-only; used internally for Peppol transmission. See Peppol Transmission Status.
`meta_info`	object	—	System-generated	Peppol transmission metadata.	Response-only. See Peppol Transmission Status.
`meta_info.peppol_status`	object	—	System-generated	Nested status with `participant_status`, `ota_status`, `overall_status`, `validation_results`.	See Peppol Transmission Status.
`document_source`	string	—	System-generated	Source of the credit note: `WEB`, `API`, or `PEPPOL`.	Create via API/UI typically returns `API` or `WEB`. Documents received over Peppol are stored as `PEPPOL`. `GET .../peppol-status` uses received-messages when source is `PEPPOL`, otherwise sent-messages.

Document status

The status field is the document lifecycle flag (distinct from Peppol transmission status in meta_info.peppol_status).

Value	Meaning
`ACTIVE`	The current version of the document. Created documents start as `ACTIVE`. List endpoints return active documents only.
`OBSOLETE`	A superseded version after edit and resubmit. The obsolete document keeps its original `uuid` and remains retrievable by id; it cannot be resubmitted again.

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

Party object

The accounting_supplier_party, accounting_customer_party, buyer_customer_party, and seller_supplier_party fields are 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. Must include OMN emirate code where applicable. See standard address structure (street_name, city_name, postal_zone, country, country_code, country_subentity).	Required; all mandatory address fields must be non-blank.
`scheme_agency_id`	string	Optional	Scheme agency identifier.	If present, must be one of `CR`, `TIN`, `PASNUM`, `CID`, `OTHID`, `ICID`, `SZLN`.
`company_id`	string	Optional	Company or registration number.	Free-form registration number; may be validated per jurisdiction.
`party_tax_scheme`	object	Required	Tax scheme with TRN. Contains `company_id`, `tax_scheme`.	Required for OMN VAT; must include a valid TRN and `tax_scheme` (usually `VAT`).
`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.

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, must follow the same rules as standard postal addresses.

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.

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 code (e.g. `EA`). See Unit of Measure Codes.	Must be a valid UN/ECE Recommendation 20 code (e.g. `EA`, `KGM`, `LTR`, `C62`).
`quantity`	number	Required	Quantity.	Must be a positive number.
`price`	object	Required	Price. On create/update: `base_amount`, `base_quantity`. Responses return `price_amount` (net) instead of `base_amount`.	Must include `base_amount` on create; `base_quantity` should be positive when provided.
`base_amount`	number	Optional	Calculated line base amount (quantity × unit price).	Response-only; distinct from `price.base_amount` on create.
`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	Tax category. Contains string `id` (`S`, `E`, `O`, `Z`), `percent`, `tax_scheme`; for `E` also `tax_exemption_reason_code` / `tax_exemption_reason`; for `Z` also `zero_rated_reason_code` / `zero_rated_reason`. See Tax Categories.	`id` must be a valid tax category; fields must match category rules.
`additional_item_identification`	array	Conditional	Client-provided	Industrial classification entries (BGOM-06 / BTOM-033). See Additional item identification object below.	Required on each line unless `transaction_type` is simplified, import of goods, import service RCM, or profit margin (IBR-081-OM). When provided, each `nature_code` must exist in the nature-code master list (`GET /api/codelist/nature-codes`).
`item_specification_document_reference`	object	Conditional	Client-provided	Item specification reference for service type classification. See Item specification document reference object below.	Required on each line unless `transaction_type` is simplified. When provided, `commodity_code` and `item_type` must be valid per OMN codelists.
`commodity_classification`	object	Optional	Client-provided	Commodity classification (e.g. Harmonised System). See Commodity classification object below.	If present, `item_classification_code` and `item_classification_list_id` are required; `item_classification_code` must exist in the item-classification master list (`GET /api/codelist/item-classification-codes`).

Additional item identification object

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

Field	Type	Required	Description	Validation
`nature_code`	string	Required	Industrial Classification Code (BTOM-033). Emitted in UBL as `AdditionalItemIdentification/cbc:ID[@schemeName='CC']`.	Must exist in MongoDB `nature_code` / `GET /api/codelist/nature-codes` (e.g. `493001`).

Item specification document reference object

The item_specification_document_reference field on a document line is an object with the following attributes:

Field	Type	Required	Description	Validation
`commodity_code`	string	Required	Service type classification code.	Must be a valid code from the service type codelist (e.g. `70000000`).
`item_type`	string	Required	Item type indicator.	Must be one of `G` (Goods) or `S` (Services).

Commodity classification object

The commodity_classification field on a document line is an object with the following attributes:

Field	Type	Required	Description	Validation
`item_classification_code`	string	Required	Commodity classification code.	Must exist in MongoDB `item_classification_codes` / `GET /api/codelist/item-classification-codes` (e.g. `500200000000` for HS).
`item_classification_list_id`	string	Required	Classification scheme identifier.	Must be a valid scheme code (e.g. `HS` for Harmonised System).
`item_classification_list_version_id`	string	Optional	Classification scheme version.	Defaults to `1.0` if omitted in responses.

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`).
`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, must be a valid tax category; may be required for VAT calculation.

Allowance object

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

Field	Type	Required	Description	Validation
`allowance_reason_code`	string	Required	UN/ECE Recommendation 20 allowance reason code.	Must be a valid UN/ECE allowance reason code (e.g. `95`).
`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, must be a valid tax category and align with invoice VAT rules.

Payment means

The payment_means field is an array of objects. Each item has the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Optional	Payment instructions ID.	Free text.
`payment_means_code`	string	Required	Payment means code (e.g. `30` for credit transfer).	Must be one of: `1`, `10`, `20`, `21`, `30`, `49`, `54`, `55`, `68`.
`payment_id`	array	Optional	Remittance / payment reference identifiers.	Array of strings; may be used for reconciliation.
`card_account`	object	Conditional	Card details. See Card account below.	Required when `payment_means_code` is `54` or `55`.
`payee_financial_account`	object	Conditional	Payee bank/financial account. See Payee financial account below.	Required when `payment_means_code` is `30`.
`payment_mandate`	object	Conditional	Direct debit mandate. See Payment mandate below.	Required when `payment_means_code` is `49`.

Card account

Field	Type	Required	Description	Validation
`primary_account_number_id`	string	Required	Card primary account number (masked PAN).	Required when `card_account` is present.
`network_id`	string	Required	Card network identifier.	Required when `card_account` is present; required for codes `54` and `55`.
`holder_name`	string	Optional	Card holder name.	Free text.

Payee financial account

Field	Type	Required	Description	Validation
`id`	string	Optional	Account identifier (e.g. IBAN).	Free text.
`name`	string	Optional	Account name.	Free text.
`financial_institution_branch_id`	string	Optional	Financial institution branch identifier.	Free text.
`address`	object	Optional	Account address.	If present, must be a valid address.

Payment mandate

Field	Type	Required	Description	Validation
`id`	string	Optional	Mandate identifier.	Free text.
`payer_financial_account_id`	string	Optional	Payer financial account identifier.	Free text.

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.
`target_currency_code`	string	Required	Target currency (ISO 4217).	Must be a valid ISO 4217 code and usually match `tax_currency_code`.
`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/OTA 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.	May be `null` in early or failed stages.
`ota_status`	string	Optional	OTA submission/processing status.	May be `null` in early or failed stages.
`overall_status`	string	Optional	Overall Peppol processing status.	Must be one of `PENDING`, `APPROVED`, `REJECTED`, `VALIDATION_FAILED`.
`validation_results`	array	Optional	Validation details/errors returned during processing.	Response-only list; empty when there are no validation issues.

Client processing guidance

For the full client processing guidance on Peppol status fields, see Peppol Transmission Status.