Marmin
BusinessesPartnersProduct Wiki

Create a purchase credit note

Creates a self-billed purchase credit note conforming to UBL 2.1 specification.

Required data

  • Original purchase invoice reference

  • Supplier party details (taxable supplier)

  • Buyer party details (credit note issuer)

  • Buyer business profile identifier

  • Line items being credited

  • Discrepancy reason

  • VAT information

System behavior

  • VAT is recalculated according to UAE VAT law

  • Credit note status and transmission events are tracked

Party VAT and registration validation
RuleDescription
Time fieldsWhen sending issue_time or delivery_time, use Gulf Standard Time (GST, UTC+4). Format HH:mm:ss.
Party VAT (party_tax_scheme)Optional for UAE supplier parties. If either company_id or tax_scheme is provided, both are required with UAE VAT format
VAT/TRN format15 numeric characters; must start with 1 and end with 01 or 03 (pattern ^1\d{12}0(01\|3)$)
Supplier registrationOptional. If scheme_agency_id is sent, company_id is required and type-specific rules apply. See The Supplier party object.
UAE supplier TINRequired for UAE suppliers. Exactly 10 characters, must start with 1
UAE supplier telephoneRequired for UAE suppliers

See The Supplier party object.

Request
POST /api/purchase-credit-notes/{business_profile_id}
Authorization: Bearer {jwt_token}
X-MARMIN-VERSION: 20260507
Response

Status code: 201 Created

Response body:

Same response structure as sales credit notes, with credit_note_type_code set to "261". Returns the created purchase credit note object with all calculated fields populated.

See the right panel for example purchase credit note JSON payloads.

Attachments

You may include an optional attachments array in the create request. Each item must include file_name, file_type, and Base64-encoded file_content. Allowed MIME types and validation rules are documented under Attachment object (request) on the Purchase credit note object page.

ConcernBehavior
Payload sizeEntire POST body must not exceed 8MB (see 413 below).
Create responseEach attachment in the 201 body includes id, file_name, and file_type only.
System PDFOn successful create, the API adds credit-note.pdf (application/pdf) for the rendered document in addition to any attachments you send.
DownloadUse Download attachment with the id from the response to fetch file bytes.
Error responses
400 Bad Request

Invalid request parameters or validation failed.

{
  "errors": {
    "message": "Business profile not found with id: {business_profile_id}"
  }
}

For validation errors, the response includes field-specific errors:

{
  "errors": {
    "profile_execution_id": "Profile execution ID is mandatory",
    "issue_date": "Issue date is mandatory"
  }
}
401 Unauthorized

Authentication required or invalid token.

{
  "errors": {
    "message": "Authentication required or invalid token"
  }
}
413 Request Entity Too Large

The request payload size exceeds the allowed limit of 8MB.

{
  "errors": {
    "message": "Payload size should not exceed 8MB"
  }
}
500 Internal Server Error

An error occurred while processing the request.

{
  "errors": {
    "message": "An error occurred"
  }
}
Next