API Docs

Create a sales credit note

Creates a sales credit note conforming to UBL 2.1 specification. See the right panel for request samples and response JSON.

Path parameters

Parameter	Type	Required	Description
`supplier_profile_id`	string	Required	The business profile ID of the supplier issuing the credit note.

Required data

Original sales invoice reference — Include the original invoice in billing_reference
Supplier profile identifier — Business profile ID of the supplier (in path)
Buyer party details — Customer party fields (name, address, tax scheme)
Line items being credited — At least one document line
Discrepancy reason — discrepancy_response
VAT information — Tax category and scheme per line and for charges/allowances as applicable

System behavior

VAT is recalculated according to OMN VAT law
Credit note status and transmission events are tracked

Response

Status code: 201 Created

Returns the created credit note object with all calculated fields populated.

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).

System-generated fields

Field	Description
`seller_uuid`	Seller identity UUID (BTOM-004). Auto-generated if omitted. See Invoice QR Code and Seller UUID.
`qr_code_base64`	Base64-encoded PNG QR code per Oman SRA v1.0.2. See Invoice QR Code and Seller UUID.

Error responses

Status	Description
400 Bad Request	Invalid request parameters or validation failed. For validation errors, the response includes field-specific errors.
401 Unauthorized	Authentication required or invalid token.
500 Internal Server Error	An error occurred while processing the request.

Request

# Base URL: https://api-sandbox.om.marmin.ai
# POST /api/sales-credit-notes/{supplier_profile_id}

curl -X POST "https://api-sandbox.om.marmin.ai/api/sales-credit-notes/MBP-1234567890abcdef" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_type": "1XXXXXXXXXXXXXXXXXXX",
    "issue_date": "2025-05-24",
    "issue_time": "10:30:00",
    "note": "Thank you for your business",
    "credit_note_type_code": "381",
    "document_currency_code": "OMR",
    "accounting_cost": "COST-001",
    "buyer_reference": "BR-REF-001",
    "invoice_period": {
      "start_date": "2025-05-01",
      "end_date": "2025-05-31",
      "description": "May 2025"
    },
    "order_reference": { "id": "ORD-001", "sales_order_id": "SO-001" },
    "billing_reference": [{ "id": "INV-PRE-001", "issue_date": "2025-04-15" }],
    "buyer_customer_party": { "id": "CUST-001" },
    "seller_supplier_party": { "id": "SUP-001" },
    "delivery": {
      "actual_delivery_date": "2025-05-25",
      "delivery_location": {
        "id": "LOC-001",
        "address": {
          "street_name": "456 Delivery St",
          "city_name": "Muscat",
          "postal_zone": "54321",
          "country_subentity": "MO",
          "country": "Oman",
          "country_code": "OM"
        }
      }
    },
    "payment_terms": {
      "payment_means_id": "abc",
      "note": "Payment",
      "amount": 100.0,
      "installment_due_date": "2025-04-08"
    },
    "charges": [{
      "reason_code": "FC",
      "reason": "Freight charge",
      "amount": 50.0,
      "tax_category": { "id": "S", "percent": 5.0, "tax_scheme": "VAT" }
    }],
    "allowances": [{
      "reason_code": "95",
      "reason": "Discount",
      "amount": 10.0,
      "tax_category": { "id": "S", "percent": 5.0, "tax_scheme": "VAT" }
    }],
    "discrepancy_response": "DL8.61.1.A",
    "accounting_customer_party": {
      "endpoint_id": "marmin1-1729456038",
      "endpoint_scheme_id": "0235",
      "party_name": "Marmin UOM - Shashank Sandbox Seller",
      "profile_id": "MBP-LEUYV0IANC",
      "postal_address": {
        "street_name": "Address",
        "additional_street_name": "Address",
        "city_name": "City",
        "postal_zone": "12312",
        "country_subentity": "MO",
        "country": "Oman",
        "country_code": "OM"
      },
      "party_tax_scheme": { "company_id": "100200201200503", "tax_scheme": "VAT" },
      "tin": "1729456038",
      "scheme_agency_id": "EID",
      "company_id": "1234567111",
      "name": "Marmin UOM - Shashank Sandbox Seller",
      "email": "sr@marmin.ai",
      "telephone": "919632802392"
    },
    "due_date": "2025-06-24",
    "payment_means": [
      {
        "id": "875849",
        "payment_means_code": "30",
        "payment_id": ["PAY-REF-001"],
        "card_account": {
          "primary_account_number_id": "58945",
          "network_id": "net-id",
          "holder_name": "card holder name"
        },
        "payee_financial_account": {
          "id": "IBAN123",
          "name": "Account Name",
          "financial_institution_branch_id": null,
          "address": null
        },
        "payment_mandate": {
          "id": "3487348",
          "payer_financial_account_id": "Pay-man-acc-id"
        }
      }
    ],
    "project_reference": { "id": "PRJ-001" },
    "prepaid_amount": 0.0,
    "payable_rounding_amount": 0.0,
    "document_lines": [{
      "quantity": 2.0,
      "unit_code": "EA",
      "order_line_reference": { "line_id": "LINE-001" },
      "description": "Product A description",
      "name": "Product A",
      "additional_item_identification": [{ "nature_code": "493001" }],
      "item_specification_document_reference": { "commodity_code": "70000000", "item_type": "S" },
      "commodity_classification": { "item_classification_code": "500200000000", "item_classification_list_id": "HS" },
      "classified_tax_category": { "id": "S", "percent": 5.0, "tax_scheme": "VAT" },
      "price": { "base_amount": 100.0, "base_quantity": 1.0 }
    }],
    "document_source": "API"
  }'

Response

{
  "document_number": "CN-001",
  "issue_date": "2026-04-22",
  "issue_time": "10:30:00",
  "credit_note_type_code": "381",
  "transaction_type": "1XXXXXXXXXXXXXXXXXXX",
  "discrepancy_response": "DL8.61.1.B",
  "document_currency_code": "OMR",
  "document_source": "API",
  "billing_reference": [
    {
      "id": "INV-1",
      "issue_date": "2026-04-20"
    }
  ],
  "accounting_customer_party": {
    "party": {
      "name": "Buyer Party",
      "party_name": "Buyer Business",
      "profile_id": "BUYER-PROFILE-001",
      "postal_address": {
        "street_name": "456 Buyer Ave",
        "city_name": "Muscat",
        "postal_zone": "67890",
        "country_subentity": "MO",
        "country": "Oman",
        "country_code": "OM"
      },
      "scheme_agency_id": "CID",
      "company_id": "765874932",
      "party_tax_scheme": {
        "company_id": "OM1109876543",
        "tax_scheme": "VAT"
      },
      "endpoint_id": "BUYER1234",
      "endpoint_scheme_id": "002"
    }
  },
  "document_lines": [
    {
      "name": "Sample Item",
      "description": "Sample Item Description",
      "quantity": 2.0,
      "unit_code": "EA",
      "price": {
        "base_amount": 100.0,
        "base_quantity": 1.0
      },
      "classified_tax_category": {
        "id": "S",
        "percent": 5.0,
        "tax_scheme": "VAT"
      }
    }
  ]
}