JSR Tax Advisors logoAPI
Developer APIsReference documentation

Create a sales invoice

Creates a sales invoice conforming to UBL 2.1 with PINT OM customization. See the right panel for request samples and response JSON.

Path parameters
ParameterTypeRequiredDescription
supplier_profile_idstring
Required
The business profile ID of the supplier issuing the invoice. Must exist in your organization.
Required data

  • Customer party — accounting_customer_party.party with name, address, tax scheme, and electronic address

  • Supplier profile identifier — Business profile ID of the supplier (in path); accounting_supplier_party.party is populated from the profile when omitted

  • Line items — At least one document_lines[] entry with quantity, unit code, price, and classified tax category

  • Transaction type — transaction_type (20-character BTOM-001 bitmap)

  • VAT information — Tax category and scheme per line and for charges/allowances as applicable

See Request payload for the full UBL-aligned field catalogue.

System behavior

  • VAT rules are applied according to OMN VAT law

  • The sales invoice is recorded

  • Invoice status and transmission events are tracked

Validation

Field-level validation is enforced by the PINT OM rule engines (UBL and jurisdiction-aligned). See:

The API returns HTTP 400 with field-specific errors when a rule fails.

Response

Status code: 201 Created

The API returns an invoice object containing all request fields plus calculated fields.

System-generated fields
FieldDescription
idUnique identifier
uuidUUID for Peppol network integration
seller_uuidSeller identity UUID (BTOM-004). Auto-generated if omitted. See Invoice QR Code and Seller UUID.
qr_code_base64Base64-encoded PNG QR code per Oman SRA v1.0.2. See Invoice QR Code and Seller UUID.
document_numberInvoice number (auto-generated if auto-numbering enabled)
document_sequenceSequential number within organization
Calculated monetary totals
FieldDescription
line_extension_amountSum of all line item amounts before tax
tax_exclusive_amountTotal before tax (line extension + charges − allowances)
tax_amountTotal VAT amount
tax_amount_in_omrTotal VAT amount in OMR (if different currency used)
tax_inclusive_amountTotal including tax
payable_amountFinal amount to be paid
payable_amount_in_omrFinal amount in OMR (if different currency used)
allowance_total_amountTotal of all document-level allowances
charge_total_amountTotal of all document-level charges
total_item_allowancesTotal of all line-level allowances
total_item_chargesTotal of all line-level charges
total_taxable_amountTotal taxable amount
total_non_taxable_amountTotal non-taxable amount
Additional response fields
FieldDescription
tax_breakdownTax amounts grouped by tax category
Document lines in response

Each line includes calculated fields: base_amount, net_amount, total_amount, tax_amount. The price object in the response contains price_amount (instead of base_amount in the request).

Charges and allowances

  • Document-level charges and allowances are applied after line item totals

  • Line-level charges and allowances are applied per line item

  • All charges and allowances require a tax_category for proper VAT calculation

  • The reason code field uses UN/ECE Recommendation 20 codes (e.g. FC for freight charges, 95 for early payment discount, 100 for volume discount)

See the right panel for complete response examples.

Error responses
StatusDescription
400 Bad RequestInvalid request parameters or validation failed. For validation errors, the response includes field-specific errors.
401 UnauthorizedAuthentication required or invalid token.
500 Internal Server ErrorAn error occurred while processing the request.