Skip to main content
Version: 2.4

Billing Blueprint

This document provides a practical blueprint for monthly billing in tSM and shows where ocs.io integration fits for advanced calculation scenarios.

Simplification Scope

This is a simplified, documentation-oriented example for architecture understanding. It does not model full tax legislation, complete receivables accounting, or full online charging mediation pipelines.

1. Business Context​

Operator goal:

  • generate monthly invoices from active services and service history,
  • apply prorate for partial-period service activity,
  • produce invoice and corrective document types,
  • print and send invoices to customers,
  • optionally export documents to finance/SAP integration flow.

2. Monthly Billing Flow in tSM​

3. Example Configuration​

3.1 Billing Cycle Type​

{
  "code": "MONTHLY.STANDARD",
  "name": "Monthly Standard Billing",
  "automatically": true,
  "billingFrequency": "MONTHLY",
  "billingDate": 1,
  "managerReportDate": 2
}

3.2 Billing Cycle​

{
  "code": "BC-2026-01",
  "name": "Billing Cycle January 2026",
  "billingCycleType": "MONTHLY.STANDARD",
  "billingCycleStatus": "TO_BE_BILLED",
  "periodFrom": "2026-01-01T00:00:00.000+00:00",
  "periodTo": "2026-01-31T23:59:59.999+00:00"
}

3.3 Billing Document and Lines​

{
  "document": {
    "key": "INV-2026-000145",
    "name": "Invoice January 2026",
    "status": "DRAFT",
    "billingCycle": "BC-2026-01",
    "customerId": "CUST-100245",
    "billingDocumentType": "INVOICE.STANDARD",
    "billingCurrencyCode": "CZK",
    "invoiceDate": "2026-02-01T00:00:00.000+00:00",
    "dueDate": "2026-02-15T00:00:00.000+00:00",
    "priceWithVat": 1995.0
  },
  "lines": [
    {
      "name": "Internet Service Monthly Fee",
      "billingDocumentCode": "INV-2026-000145",
      "quantity": 1,
      "priceWithoutVAT": 1500.0,
      "vat": 21.0,
      "sortOrder": 10
    },
    {
      "name": "Public IP (Prorated 10/31 days)",
      "billingDocumentCode": "INV-2026-000145",
      "quantity": 1,
      "priceWithoutVAT": 161.29,
      "vat": 21.0,
      "sortOrder": 20
    }
  ]
}

3.4 SAP Export Package​

{
  "status": "READY",
  "billingCycle": "BC-2026-01",
  "customerId": "CUST-100245",
  "hasCsv": true,
  "billingDocumentIds": [
    "2f878073-bfe6-41a2-8e1d-52ef5ba06f7c"
  ]
}

4. Prorate Rule Example​

Simple prorate formula used in recurring charge scenarios:

proratedCharge = fullMonthlyCharge * activeDaysInPeriod / daysInBillingPeriod

Example:

  • full monthly fee: 500 CZK
  • active days: 10
  • month length: 31
  • prorated charge: 500 * 10 / 31 = 161.29 CZK

5. Advanced Extension with ocs.io Calculation​

When business scope expands beyond cycle invoicing:

  • CDR streams are fed to ocs.io charging/rating calculation,
  • tSM keeps full billing UI, document lifecycle, and process orchestration,
  • customer bill outputs can still be synchronized back to tSM-facing channels and finance exports via TMF-aligned contracts.

This gives a phased architecture:

  1. run periodic billing end-to-end in tSM,
  2. add ocs.io for high-scale/advanced charging calculations,
  3. keep TMF API contracts and shared customer/account context consistent across both layers.