Quick Start — CloudSync Pro

Build a complete billing scenario from scratch: create a cloud storage offer with three pricing models, onboard a customer, submit usage, and generate an invoice.

By the end you'll have invoiced Atlas Digital for a monthly platform fee, metered storage, and API calls.

Prerequisites

• A running Billerang instance (Docker or K8s — see Installation)
• API credentials (OAuth client ID and secret — see Authentication)
• curl or Postman

Get a Token

# Store your credentials (from .credentials file or Keycloak admin)
export KEYCLOAK_URL="http://localhost:8080/realms/billerang/protocol/openid-connect/token"
export CLIENT_ID="your-client-id"
export CLIENT_SECRET="your-client-secret"

# Get bearer token
TOKEN=$(curl -s -X POST "$KEYCLOAK_URL" \
  -d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

echo $TOKEN

All API calls below use this header:

-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json"

---

Step 1: Global Setup

Before creating any business entities, set up the foundation: language, currency, country, and invoice configuration.

Trading Language

curl -X POST "http://localhost:8080/api/v1/tradingLanguages" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "code": "EN",
    "description": "English",
    "languageCode": "en"
  }'

Trading Currency

curl -X POST "http://localhost:8080/api/v1/tradingCurrencies" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "code": "USD",
    "description": "US Dollar",
    "currencyCode": "USD"
  }'

Trading Country

curl -X POST "http://localhost:8080/api/v1/tradingCountries" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "code": "US",
    "description": "United States",
    "countryCode": "US"
  }'

Title (Legal Entity Type)

curl -X POST "http://localhost:8080/api/rest/account/title/createOrUpdate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "title": {
      "code": "COMPANY",
      "description": "Company",
      "isCompany": true
    }
  }'

Invoice Sequence & Type

# Create invoice sequence
curl -X POST "http://localhost:8080/api/rest/invoiceSequence/" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "invoiceSequence": {
      "code": "INV_SEQ_BAM",
      "description": "BAM Invoice Sequence",
      "sequenceSize": 9,
      "currentInvoiceNb": 1
    }
  }'

# Create invoice type
curl -X POST "http://localhost:8080/api/rest/invoiceType/" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "invoiceType": {
      "code": "COMMERCIAL",
      "description": "Commercial Invoice",
      "invoiceSequenceCode": "INV_SEQ_BAM"
    }
  }'

---

Step 2: Create Seller "BAM"

BAM (Business Account Manager) is the organizational unit that owns customers.

curl -X POST "http://localhost:8080/api/v1/sellers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "code": "BAM",
    "description": "Business Account Manager",
    "tradingLanguage": "EN",
    "tradingCurrency": "USD",
    "tradingCountry": "US",
    "invoiceTypeCode": "COMMERCIAL"
  }'

---

Step 3: Create Customer "Atlas Digital"

Use the atomic hierarchy endpoint to create the full account structure in one call: Customer, CustomerAccount, BillingAccount, and UserAccount.

curl -X POST "http://localhost:8080/api/rest/account/accountHierarchy/customerHierarchyUpdate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "crmAccountHierarchy": {
      "crmAccountType": "C_BA_UA",
      "code": "ATLAS_DIGITAL",
      "description": "Atlas Digital Inc.",
      "name": { "firstName": "Atlas", "lastName": "Digital", "title": "COMPANY" },
      "seller": "BAM",
      "currency": "USD",
      "country": "US",
      "language": "EN",
      "email": "billing@atlasdigital.com",
      "billingCycle": "CYC_INV_MT_1"
    }
  }'

This creates:

• Customer ATLAS_DIGITAL — the company
• CustomerAccount ATLAS_DIGITAL_CA — financial grouping
• BillingAccount ATLAS_DIGITAL_BA — where invoices are sent
• UserAccount ATLAS_DIGITAL_UA — where subscriptions attach

---

Step 4: Build the CloudSync Pro Offer

Three charges, three pricing models — demonstrating the flexibility of the catalog.

4a. Recurring Charge — Platform Fee (Flat $49.99/month)

# Create the recurring charge
curl -X POST "http://localhost:8080/api/v1/recurringCharges" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "code": "CHG_PLATFORM_FEE",
    "description": "CloudSync Platform Fee",
    "invoiceSubCategory": "REC_CHARGES",
    "calendar": "CAL_MONTHLY"
  }'

# Add flat pricing: $49.99/month
curl -X POST "http://localhost:8080/api/v1/charges/CHG_PLATFORM_FEE/pricingVersions" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "pricingType": "FLAT",
    "price": 49.99,
    "currencyCode": "USD"
  }'

# Publish the pricing version
curl -X PUT "http://localhost:8080/api/v1/charges/CHG_PLATFORM_FEE/pricingVersions/1/publish" \
  -H "Authorization: Bearer $TOKEN"

4b. Usage Charge — Storage (Matrix Pricing: Region x Tier)

Multi-attribute matrix pricing — the price depends on the combination of region and storage tier.

# Create usage charge
curl -X POST "http://localhost:8080/api/v1/usageCharges" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "code": "CHG_STORAGE",
    "description": "CloudSync Storage",
    "invoiceSubCategory": "USAGE_CHARGES",
    "ratingUnitDescription": "GB",
    "unitMultiplicator": 1
  }'

# Add matrix pricing with 2 attributes: region + storageTier
curl -X POST "http://localhost:8080/api/v1/charges/CHG_STORAGE/pricingVersions" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "pricingType": "MATRIX",
    "currencyCode": "USD",
    "matrixColumns": [
      { "attribute": "region", "type": "STRING" },
      { "attribute": "storageTier", "type": "STRING" }
    ],
    "matrixRows": [
      { "values": ["US", "Standard"], "price": 0.023 },
      { "values": ["US", "Premium"],  "price": 0.050 },
      { "values": ["EU", "Standard"], "price": 0.025 },
      { "values": ["EU", "Premium"],  "price": 0.055 }
    ]
  }'

# Publish
curl -X PUT "http://localhost:8080/api/v1/charges/CHG_STORAGE/pricingVersions/1/publish" \
  -H "Authorization: Bearer $TOKEN"

Resulting price matrix:

Region	Tier	Price per GB
US	Standard	$0.023
US	Premium	$0.050
EU	Standard	$0.025
EU	Premium	$0.055

4c. Usage Charge — API Calls (Formula Pricing)

First 10,000 calls free, then $0.001 per call. Uses a formula expression.

# Create usage charge
curl -X POST "http://localhost:8080/api/v1/usageCharges" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "code": "CHG_API_CALLS",
    "description": "CloudSync API Calls",
    "invoiceSubCategory": "USAGE_CHARGES",
    "ratingUnitDescription": "calls",
    "unitMultiplicator": 1
  }'

# Add formula pricing
curl -X POST "http://localhost:8080/api/v1/charges/CHG_API_CALLS/pricingVersions" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "pricingType": "FORMULA",
    "currencyCode": "USD",
    "formula": "max(0, (quantity - 10000) * 0.001)"
  }'

# Publish
curl -X PUT "http://localhost:8080/api/v1/charges/CHG_API_CALLS/pricingVersions/1/publish" \
  -H "Authorization: Bearer $TOKEN"

Pricing logic: max(0, (quantity - 10000) * 0.001)

• 5,000 calls → $0.00 (within free tier)
• 25,000 calls → (25000 - 10000) x 0.001 = $15.00

4d. Create the Offer Template

Bundle all three charges into a single offer.

curl -X POST "http://localhost:8080/api/v1/offerTemplates" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "code": "OFF_CLOUDSYNC_PRO",
    "description": "CloudSync Pro — Platform + Storage + API",
    "charges": [
      { "chargeCode": "CHG_PLATFORM_FEE", "chargeType": "RECURRING" },
      { "chargeCode": "CHG_STORAGE", "chargeType": "USAGE" },
      { "chargeCode": "CHG_API_CALLS", "chargeType": "USAGE" }
    ]
  }'

# Activate the offer
curl -X PUT "http://localhost:8080/api/v1/offerTemplates/OFF_CLOUDSYNC_PRO/status" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "status": "ACTIVE" }'

---

Step 5: Subscribe via Order API

Create a commercial order to subscribe Atlas Digital to CloudSync Pro.

# Create order
curl -X POST "http://localhost:8080/api/rest/v2/orders" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "order": {
      "code": "ORD_ATLAS_001",
      "description": "Atlas Digital — CloudSync Pro subscription",
      "sellerCode": "BAM",
      "billingAccountCode": "ATLAS_DIGITAL_BA",
      "orderItems": [
        {
          "offerTemplateCode": "OFF_CLOUDSYNC_PRO",
          "userAccountCode": "ATLAS_DIGITAL_UA",
          "subscriptionCode": "SUB_ATLAS_CLOUDSYNC",
          "quantity": 1
        }
      ]
    }
  }'

# Validate order → creates the subscription
curl -X PUT "http://localhost:8080/api/rest/v2/orders/ORD_ATLAS_001/orderValidation" \
  -H "Authorization: Bearer $TOKEN"

After validation, a Subscription SUB_ATLAS_CLOUDSYNC is created and activated with all three charges.

---

Step 6: Submit Usage (CDRs)

Inject usage events that will be rated against the matrix and formula pricing.

Storage Usage — 500 GB in US/Standard

curl -X POST "http://localhost:8080/api/rest/billing/mediation/chargeCdr" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "cdr": {
      "accessCode": "SUB_ATLAS_CLOUDSYNC",
      "quantity": 500,
      "eventDate": "2026-04-01T00:00:00Z",
      "param1": "CHG_STORAGE",
      "extraParam": {
        "region": "US",
        "storageTier": "Standard"
      }
    }
  }'

Rated: 500 GB x $0.023 = $11.50

API Calls — 25,000 calls

curl -X POST "http://localhost:8080/api/rest/billing/mediation/chargeCdr" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "cdr": {
      "accessCode": "SUB_ATLAS_CLOUDSYNC",
      "quantity": 25000,
      "eventDate": "2026-04-01T00:00:00Z",
      "param1": "CHG_API_CALLS"
    }
  }'

Rated: max(0, (25000 - 10000) x 0.001) = $15.00

---

Step 7: Run Billing & Download Invoice

Execute Billing Run

curl -X POST "http://localhost:8080/api/rest/billing/billingRun" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "billingRun": {
      "billingCycleCode": "CYC_INV_MT_1",
      "billingRunType": "FULL",
      "startDate": "2026-04-01",
      "endDate": "2026-04-30"
    }
  }'

List Invoices

curl -X GET "http://localhost:8080/api/rest/billing/invoice?billingAccountCode=ATLAS_DIGITAL_BA" \
  -H "Authorization: Bearer $TOKEN"

Download Invoice PDF

curl -X GET "http://localhost:8080/api/rest/billing/invoice/{invoiceId}/pdf" \
  -H "Authorization: Bearer $TOKEN" \
  -o atlas_digital_april_2026.pdf

---

Expected Invoice

Line	Description	Calculation	Amount
Platform Fee	Monthly recurring (flat)	$49.99	$49.99
Storage	500 GB, US/Standard (matrix)	500 x $0.023	$11.50
API Calls	25,000 calls (formula)	(25000 - 10000) x $0.001	$15.00
		Total	$76.49

---

What's Next?

• Pricing Patterns — Explore all 8 pricing models (tiered, volume, package, percentage, and more)
• Prepaid Wallets — Set up balance-based billing with reservations
• Orders API — Order capture, validation, preview, milestone billing
• API v1 Introduction — The full v1 surface by domain
• Real-World Scenarios — See how Netflix, OpenAI, and Pluxee use these patterns