{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/ordogrid/json-schema/ordogrid-document-schema.json",
  "title": "Document",
  "description": "Shared shape for invoices, quotes, credit notes and receipts.",
  "x-generated": "2026-11-02",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ordogrid-openapi.json#/components/schemas/Document",
  "properties": {
    "amount_paid": {
      "type": [
        "number",
        "null"
      ]
    },
    "attachments": {
      "items": {
        "$ref": "#/$defs/Attachment"
      },
      "type": "array"
    },
    "client": {
      "anyOf": [
        {
          "$ref": "#/$defs/Participant"
        },
        {
          "type": "null"
        }
      ]
    },
    "communication": {
      "type": [
        "string",
        "null"
      ]
    },
    "created_at": {
      "description": "UTC, ISO 8601 with milliseconds and Z, e.g. 2026-10-22T10:00:00.123Z.",
      "format": "date-time",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$",
      "type": [
        "string",
        "null"
      ]
    },
    "credited_invoice": {
      "description": "Credit notes only: the invoice credited. `id` is the OrdoGrid invoice id, or null for an invoice issued outside the platform (credit_for_invoice_number), whose issue_date is unknown. Null on every other document.",
      "properties": {
        "id": {
          "type": [
            "string",
            "null"
          ]
        },
        "issue_date": {
          "format": "date",
          "type": [
            "string",
            "null"
          ]
        },
        "number": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": [
        "object",
        "null"
      ]
    },
    "currency": {
      "type": [
        "string",
        "null"
      ]
    },
    "delivery_date": {
      "description": "Date of supply (Peppol BT-72) when it differs from issue_date. Invoices and credit notes only.",
      "format": "date",
      "type": [
        "string",
        "null"
      ]
    },
    "document_revision": {
      "type": "integer"
    },
    "document_snapshot": {
      "anyOf": [
        {
          "$ref": "#/$defs/DocumentSnapshot"
        },
        {
          "type": "null"
        }
      ]
    },
    "due_date": {
      "format": "date",
      "type": [
        "string",
        "null"
      ]
    },
    "external_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "global_discount": {
      "description": "The entered document discount, or null. Its amount is totals.global_discount.",
      "properties": {
        "amount_basis": {
          "enum": [
            "net",
            "gross"
          ],
          "type": "string"
        },
        "type": {
          "enum": [
            "percentage",
            "fixed"
          ],
          "type": "string"
        },
        "value": {
          "type": "number"
        },
        "value_exact": {
          "readOnly": true,
          "type": "string"
        }
      },
      "type": [
        "object",
        "null"
      ]
    },
    "has_pdf": {
      "type": "boolean"
    },
    "id": {
      "type": [
        "string",
        "null"
      ]
    },
    "integration_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "issue_date": {
      "format": "date",
      "type": [
        "string",
        "null"
      ]
    },
    "items": {
      "items": {
        "$ref": "#/$defs/DocumentItem"
      },
      "type": "array"
    },
    "lifecycle": {
      "description": "Coarse bucket, e.g. draft, active, done.",
      "type": [
        "string",
        "null"
      ]
    },
    "note": {
      "type": [
        "string",
        "null"
      ]
    },
    "number": {
      "type": [
        "string",
        "null"
      ]
    },
    "object": {
      "enum": [
        "invoice",
        "quote",
        "credit_note",
        "receipt"
      ],
      "type": "string"
    },
    "payment_date": {
      "description": "UTC, ISO 8601 with milliseconds and Z, e.g. 2026-10-22T10:00:00.123Z.",
      "format": "date-time",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$",
      "type": [
        "string",
        "null"
      ]
    },
    "payment_method": {
      "type": [
        "string",
        "null"
      ]
    },
    "prices_include_vat": {
      "type": "boolean"
    },
    "purchase_order": {
      "type": [
        "string",
        "null"
      ]
    },
    "settlement": {
      "anyOf": [
        {
          "$ref": "#/$defs/Settlement"
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "description": "Bare state, e.g. draft, sent, paid.",
      "type": [
        "string",
        "null"
      ]
    },
    "structured_communication": {
      "type": [
        "string",
        "null"
      ]
    },
    "supplier": {
      "anyOf": [
        {
          "$ref": "#/$defs/Participant"
        },
        {
          "type": "null"
        }
      ]
    },
    "tax_reporting": {
      "items": {
        "$ref": "#/$defs/MarginTaxReport"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "totals": {
      "description": "Discount amounts are net of VAT, also when prices_include_vat is true.",
      "properties": {
        "discounts": {
          "description": "line_discounts + global_discount: the discount total printed on the PDF.",
          "type": "number"
        },
        "global_discount": {
          "description": "The document discount, allocated across the lines.",
          "type": "number"
        },
        "gross": {
          "type": "number"
        },
        "line_discounts": {
          "description": "Sum of the line discounts.",
          "type": "number"
        },
        "net": {
          "description": "net_before_discounts - discounts.",
          "type": "number"
        },
        "net_before_discounts": {
          "description": "Sum of the line net amounts before any discount.",
          "type": "number"
        },
        "payable": {
          "description": "Commercial total including rounding, before prepayments.",
          "type": "number"
        },
        "rounding": {
          "type": "number"
        },
        "vat": {
          "type": "number"
        }
      },
      "type": "object"
    },
    "transaction_reference": {
      "type": [
        "string",
        "null"
      ]
    },
    "updated_at": {
      "description": "UTC, ISO 8601 with milliseconds and Z, e.g. 2026-10-22T10:00:00.123Z.",
      "format": "date-time",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$",
      "type": [
        "string",
        "null"
      ]
    },
    "vat_treatment": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "type": "object",
  "$defs": {
    "Address": {
      "properties": {
        "city": {
          "type": [
            "string",
            "null"
          ]
        },
        "country": {
          "type": [
            "string",
            "null"
          ]
        },
        "country_code": {
          "type": [
            "string",
            "null"
          ]
        },
        "postal_code": {
          "type": [
            "string",
            "null"
          ]
        },
        "street": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "street",
        "city",
        "postal_code",
        "country",
        "country_code"
      ],
      "type": "object"
    },
    "Attachment": {
      "properties": {
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "filename": {
          "type": [
            "string",
            "null"
          ]
        },
        "id": {
          "type": [
            "string",
            "null"
          ]
        },
        "mime_type": {
          "type": [
            "string",
            "null"
          ]
        },
        "size": {
          "type": [
            "integer",
            "null"
          ]
        },
        "uploaded_at": {
          "description": "UTC, ISO 8601 with milliseconds and Z, e.g. 2026-10-22T10:00:00.123Z.",
          "format": "date-time",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "DocumentItem": {
      "properties": {
        "description": {
          "type": "string"
        },
        "discount": {
          "properties": {
            "amount_basis": {
              "enum": [
                "net",
                "gross"
              ],
              "type": "string"
            },
            "type": {
              "enum": [
                "percentage",
                "fixed"
              ],
              "type": "string"
            },
            "value": {
              "type": "number"
            },
            "value_exact": {
              "readOnly": true,
              "type": "string"
            }
          },
          "type": [
            "object",
            "null"
          ]
        },
        "price_basis": {
          "default": "net",
          "enum": [
            "net",
            "gross"
          ],
          "type": "string"
        },
        "quantity": {
          "type": [
            "number",
            "string"
          ]
        },
        "quantity_exact": {
          "readOnly": true,
          "type": "string"
        },
        "source_unit_price": {
          "description": "Exact entered price in price_basis. Gross prices are authoritative; unit_price remains the compatible net price.",
          "type": "string"
        },
        "unit": {
          "description": "UN/ECE code, e.g. C62 (piece).",
          "type": [
            "string",
            "null"
          ]
        },
        "unit_price": {
          "type": [
            "number",
            "string"
          ]
        },
        "unit_price_exact": {
          "readOnly": true,
          "type": "string"
        },
        "vat_rate": {
          "type": [
            "number",
            "null"
          ]
        },
        "vat_type": {
          "enum": [
            "standard",
            "exempt",
            "exempt_art44",
            "reverse_charge",
            "cocontractant",
            "intracommunity",
            "zero_rated",
            "export",
            "margin",
            null
          ],
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "DocumentSnapshot": {
      "properties": {
        "calculation_version": {
          "type": "integer"
        },
        "created_at": {
          "description": "UTC, ISO 8601 with milliseconds and Z, e.g. 2026-10-22T10:00:00.123Z.",
          "format": "date-time",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$",
          "type": "string"
        },
        "currency": {
          "type": "string"
        },
        "document_revision": {
          "type": "integer"
        },
        "document_total": {
          "description": "Exact decimal currency amount; no binary arithmetic. Precision follows capabilities.currencies.",
          "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
          "type": "string"
        },
        "payable_amount": {
          "description": "Exact decimal currency amount; no binary arithmetic. Precision follows capabilities.currencies.",
          "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
          "type": "string"
        },
        "prepayments": {
          "description": "Exact decimal currency amount; no binary arithmetic. Precision follows capabilities.currencies.",
          "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
          "type": "string"
        },
        "rounding_amount": {
          "description": "Exact decimal currency amount; no binary arithmetic. Precision follows capabilities.currencies.",
          "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
          "type": "string"
        },
        "settlement_revision": {
          "type": "integer"
        },
        "tax_inclusive_amount": {
          "description": "Exact decimal currency amount; no binary arithmetic. Precision follows capabilities.currencies.",
          "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
          "type": "string"
        }
      },
      "type": "object"
    },
    "MarginTaxReport": {
      "description": "Private company accounting data; excluded from customer PDF/UBL.",
      "properties": {
        "currency": {
          "const": "EUR"
        },
        "margin_vat": {
          "description": "Exact decimal currency amount; no binary arithmetic. Precision follows capabilities.currencies.",
          "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
          "type": "string"
        },
        "non_taxable_consideration": {
          "description": "Exact decimal currency amount; no binary arithmetic. Precision follows capabilities.currencies.",
          "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
          "type": "string"
        },
        "purchase_price": {
          "description": "Exact decimal currency amount; no binary arithmetic. Precision follows capabilities.currencies.",
          "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
          "type": "string"
        },
        "purchase_reference": {
          "type": "string"
        },
        "reporting": {
          "properties": {
            "non_taxable_box": {
              "const": "00"
            },
            "taxable_box": {
              "const": "03"
            },
            "vat_box": {
              "const": "54"
            }
          },
          "type": "object"
        },
        "selling_price": {
          "description": "Exact decimal currency amount; no binary arithmetic. Precision follows capabilities.currencies.",
          "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
          "type": "string"
        },
        "taxable_margin": {
          "description": "Exact decimal currency amount; no binary arithmetic. Precision follows capabilities.currencies.",
          "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
          "type": "string"
        }
      },
      "type": "object"
    },
    "Participant": {
      "properties": {
        "address": {
          "anyOf": [
            {
              "$ref": "#/$defs/Address"
            },
            {
              "type": "null"
            }
          ]
        },
        "bic": {
          "type": [
            "string",
            "null"
          ]
        },
        "email": {
          "type": [
            "string",
            "null"
          ]
        },
        "iban": {
          "type": [
            "string",
            "null"
          ]
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "phone": {
          "type": [
            "string",
            "null"
          ]
        },
        "vat_number": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "Settlement": {
      "description": "Payments include prepayments net of reversals; credits never include cash refunds. Outstanding=max(0,total-credits-payments+refunds); refund_due=max(0,payments-refunds-(total-credits)).",
      "properties": {
        "as_of": {
          "description": "UTC, ISO 8601 with milliseconds and Z, e.g. 2026-10-22T10:00:00.123Z.",
          "format": "date-time",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$",
          "type": "string"
        },
        "credits": {
          "description": "Exact decimal currency amount; no binary arithmetic. Precision follows capabilities.currencies.",
          "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
          "type": "string"
        },
        "currency": {
          "type": "string"
        },
        "document_total": {
          "description": "Exact decimal currency amount; no binary arithmetic. Precision follows capabilities.currencies.",
          "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
          "type": "string"
        },
        "legacy_reconciliation_required": {
          "type": "boolean"
        },
        "outstanding": {
          "description": "Exact decimal currency amount; no binary arithmetic. Precision follows capabilities.currencies.",
          "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
          "type": "string"
        },
        "payments": {
          "description": "Exact decimal currency amount; no binary arithmetic. Precision follows capabilities.currencies.",
          "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
          "type": "string"
        },
        "prepayments": {
          "description": "Exact decimal currency amount; no binary arithmetic. Precision follows capabilities.currencies.",
          "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
          "type": "string"
        },
        "refund_due": {
          "description": "Exact decimal currency amount; no binary arithmetic. Precision follows capabilities.currencies.",
          "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
          "type": "string"
        },
        "refunds": {
          "description": "Exact decimal currency amount; no binary arithmetic. Precision follows capabilities.currencies.",
          "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
          "type": "string"
        },
        "revision": {
          "type": "integer"
        },
        "status": {
          "enum": [
            "unpaid",
            "partial",
            "settled",
            "refund_due"
          ],
          "type": "string"
        }
      },
      "type": "object"
    }
  }
}