This guide walks you through the minimum setup — from login to your first DR with an assigned price. You can do it in 10 minutes.

Every step can be done via the Dashboard or directly via the API — your choice.

Overview

1. Login
2. Create a price list + version + items
3. Create a pricing rule
4. Send a DR
5. Get a billing summary

Step 1 — Login

Dashboard: Sign in at /dashboard with your credentials.

API:

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "your_login",
  "password": "your_password"
}

The response returns a token. Add it to every subsequent request:

Authorization: Bearer <token>

Step 2 — Price List, Version, and Items

A price list tells the system how much each type of record costs. The structure has three levels: Price List → Version → Items.

2a — Create a Price List

Dashboard: Go to Price Lists → click Add Price List.

API:

POST /api/v1/price-lists
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Standard Price List",
  "currency": "EUR"
}

Response: { "id": "<price_list_id>" } — save this.

2b — Create a Price List Version

A version defines when prices take effect. It must have is_active: true to be used.

Dashboard: Open the price list → Versions tab → Add Version.

API:

POST /api/v1/price-lists/<price_list_id>/versions
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "v1",
  "valid_from": "2024-01-01T00:00:00Z",
  "is_active": true
}

Response: { "id": "<version_id>" } — save this.

2c — Add a Price List Item

An item says: “For code VOICE_CZ, charge €0.06 per unit.”

Dashboard: Open the version → Add Item.

API:

POST /api/v1/price-lists/versions/<version_id>/items
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "VOICE_CZ",
  "name": "Voice Call CZ",
  "price": 0.06,
  "currency": "EUR",
  "unit": "minute"
}

The code value must exactly match the code field in the DR you send in Step 4.

Step 3 — Pricing Rule

A pricing rule links a price list to your customers. Without a rule, the system doesn’t know which price list to use.

The setup below applies the price list to all your customers.

Dashboard: Go to Pricing Rules → Add Rule, select the price list.

API:

POST /api/v1/pricing-rules
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Default Rule",
  "code": "RULE_DEFAULT",
  "price_list_id": "<price_list_id>",
  "priority": 10,
  "is_active": true
}

A rule without customer_id or group_id applies to all customers. To target a specific segment, add "group_id": "<group_id>".

Step 4 — Send a DR

Now send your first data record. Use "ondemand": true for immediate pricing.

You don’t need to create customers in advance. Just provide any identifier in customer_external_id — the customer is created automatically on the first record.

POST /api/v1/dr
Authorization: Bearer <token>
Content-Type: application/json

{
  "ondemand": true,
  "records": [
    {
      "code": "VOICE_CZ",
      "quantity": 10,
      "time_from": "2024-06-15T10:00:00Z",
      "customer_external_id": "CUST-001"
    }
  ]
}

Response: { "inserted": 1, "ids": ["<dr_id>"] }

What happened behind the scenes:

• Customer CUST-001 was automatically created (no personal data required)
• The system found the pricing rule → price list version → item VOICE_CZ
• Calculated price: 10 × 0.06 = €0.60
• DR saved with status rated

Step 5 — Billing Summary

Get invoice data for any period with a single call.

Dashboard: Go to Billing → set the date range → Show Summary.

API:

POST /api/v1/dr/billing
Authorization: Bearer <token>
Content-Type: application/json

{
  "time_from": "2024-06-01T00:00:00Z",
  "time_to":   "2024-06-30T23:59:59Z",
  "group_by":  "code"
}

Response:

{
  "items": [
    {
      "code": "VOICE_CZ",
      "quantity": 10,
      "amount_without_vat": 0.60,
      "vat_amount": 0.00,
      "amount": 0.60,
      "currency": "EUR"
    }
  ],
  "summary": {
    "amount_without_vat": 0.60,
    "vat_amount": 0.00,
    "amount": 0.60,
    "currency": "EUR"
  }
}

What’s Next?

• More codes — add more items to the price list version (SMS_CZ, DATA_EU, …)
• More customers — use different customer_external_id values; customers are created automatically
• Customer segmentation — create customer groups and rules with group_id
• New price version — add a version with a new valid_from; historical data stays unchanged
• Triggers — automatic charges when usage limits are exceeded

A price list in Billing Engine is a hierarchical structure consisting of versions and items.

Price List Structure

Each price list can have multiple versions — typically one is active, others are archived. Each version contains pricing items identified by a code (e.g., VOICE_CZ, SMS_CZ).

Price Calculation

When a data record (DR) arrives, the system:

1. Finds the valid price list version for the customer via pricing rules
2. Looks up the price list item matching the code from the DR
3. Calculates the price: price = quantity × unit_price

Assignment to Customers

Price lists are not assigned to customers directly. The link goes through:

• Groups — a customer belongs to a group
• Pricing rules — a rule says: for this group, use this price list

This model allows a single price list to be shared across many customers and makes it easy to switch to new versions without changing each customer’s configuration individually.

Pricing rules determine which price list and version are applied to a given data record.

How a Rule Works

Each rule defines:

• Conditions — matching criteria, e.g. code = "VOICE_CZ" or quantity > 10
• Priority — a number; higher priority = rule is evaluated first
• Target price list — which price list (and version) to use on match

The system iterates through rules from highest priority and applies the first one that matches the record.

Condition Operators

Conditions support operators: eq, ne, gt, gte, lt, lte, like, in.

{ "code": { "op": "eq", "value": "VOICE_CZ" },
  "quantity": { "op": "gt", "value": 0 } }

Triggers — a Special Type of Rule

Triggers extend rules with automated actions. They fire when:

• A single DR exceeds a limit (conditions)
• An aggregate condition over a period is met — e.g. SUM(quantity) > 100 (aggregate_conditions)

A trigger can send a notification or add a charge to the billing output.