Getting startedTutorials

Get to your first invoice

By the end of this tutorial you will have a finalized invoice in your sandbox. You’ll build the complete billing setup from scratch — meter, product, pricing plan, customer, subscription, and usage event — using the API.

What you’ll need:

  • A Solvimon sandbox API key — see Send your first API request
  • A billing entity configured under Settings → Billing entities in Desk
  • curl or any HTTP client

Overview

Solvimon’s primitives have a dependency order. You need each piece before you can create the next:

StepResourceWhat it does
1Meter + Meter ValueDefines what usage you’re measuring
2Meter Value CalculationDefines how to aggregate the usage (sum, max, etc.)
3Product Category + Product + Product ItemDefines what you sell
4Pricing PlanDefines the price and billing terms
5CustomerWho you’re billing
6SubscriptionLinks the customer to the pricing plan
7Usage EventReports actual usage
8InvoiceGenerated automatically from the subscription

Step 1: Create a meter and meter value

A meter defines what usage you’re tracking. A meter value is the unit being measured — in this case, a count of API calls.

Create the meter value

A meter value is the specific unit being tracked within a meter. Here we’re counting calls as a NUMBER type.

$curl -X POST https://test.api.solvimon.com/v1/meter-values \
>  -H "X-API-KEY: <apiKey>" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "reference": "call_count",
>    "name": "Call Count",
>    "type": "NUMBER",
>    "status": "ACTIVE"
>  }'

Response:

1{
2  "id": "metv_def456",
3  "object_type": "METER_VALUE",
4  "reference": "call_count",
5  "name": "Call Count",
6  "type": "NUMBER",
7  "status": "ACTIVE"
8}

Create the meter

$curl -X POST https://test.api.solvimon.com/v1/meters \
>  -H "X-API-KEY: <apiKey>" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "reference": "api_calls",
>    "name": "API Calls",
>    "status": "ACTIVE",
>    "meter_values": [
>        {
>          "id": "metv_def456",
>          "required": true
>        }
>      ]
>  }'

Response:

1{
2    "object_type": "METER",
3    "id": "metr_abc123",
4    "reference": "api_calls",
5    "name": "API Calls",
6    "status": "ACTIVE",
7    "meter_values": [
8        {
9            "id": "metv_def456",
10            "required": true
11        }
12    ]
13}

📘 Via Desk: Usage metering → Meters → New meter. You can create the meter value inline during meter setup.

Step 2: Create a meter value calculation

The meter value calculation ties your meter and meter value together with an aggregation method. Here we use SUM to total all API calls within a billing period.

$curl -X POST https://test.api.solvimon.com/v1/meter-value-calculations \
>  -H "X-API-KEY: <apiKey>" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "reference": "api_calls_sum",
>    "name": "API Calls Sum",
>    "meter_id": "metr_abc123",
>    "meter_value_id": "metv_def456",
>    "calculation_type": "SUM"
>  }'

Response:

1{
2  "id": "mvc_ghi789",
3  "object_type": "METER_VALUE_CALCULATION",
4  "reference": "api_calls_sum",
5  "name": "API Calls Sum",
6  "calculation_type": "SUM"
7}

Use the id or reference of this calculation when creating the product item in Step 3.

Step 3: Create a product category, product, and product item

Products define what you sell. The product item is what appears as a line item on invoices. For usage-based billing, the product item links to your meter value calculation.

Create a product category

$curl -X POST https://test.api.solvimon.com/v1/product-categories \
>  -H "X-API-KEY: <apiKey>" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "reference": "platform",
>    "name": "Platform"
>  }'

Create a product

$curl -X POST https://test.api.solvimon.com/v1/products \
>  -H "X-API-KEY: <apiKey>" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "reference": "api_access",
>    "name": "API Access",
>    "category_id": "<product_category_id>",
>    "product_type": "DEFAULT"
>  }'

Create a product item

The product item links the product to the meter value calculation. Set model_type to USAGE_BASED.

$curl -X POST https://test.api.solvimon.com/v1/product-items \
>  -H "X-API-KEY: <apiKey>" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "reference": "api_calls_item",
>    "name": "API Calls",
>    "product_id": "<product_id>",
>    "model_type": "USAGE_BASED",
>    "usage_based": {
>      "meter_value_calculation_id": "mvc_ghi789"
>    }
>  }'

Then activate the product and product item:

$curl -X POST https://test.api.solvimon.com/v1/products/api_access/activate \
>  -H "X-API-KEY: <apiKey>"
$
$curl -X POST https://test.api.solvimon.com/v1/product-items/api_calls_item/activate \
>  -H "X-API-KEY: <apiKey>"

📘 Via Desk: Products & plans → Product catalog → New product. You can create the category, product, and item from one screen and set the meter link inline.

Step 4: Create a pricing plan

A pricing plan defines the price per unit and the billing period. Pricing plans are versioned — you create the plan, then create a version with the billing configuration and product pricing.

📘 Via Desk: Products & plans → Pricing plans → New pricing plan. Desk provides a guided editor for setting up versions and pricing rules, which is recommended for your first plan. Once you’re familiar with the structure, use the Pricing Plans API reference for automation.

To create a plan via API: create the plan with POST /v1/pricing-plans, then create a version with POST /v1/pricing-plan-versions and add a pricing entry with POST /v1/pricings linking your product item and setting the per-unit price. Activate the version once configured.

Note the reference of your pricing plan — you’ll need it when creating the subscription.

Step 5: Create and activate a customer

$curl -X POST https://test.api.solvimon.com/v1/customers \
>  -H "X-API-KEY: <apiKey>" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "reference": "superstore-001",
>    "type": "ORGANIZATION",
>    "email": "invoices@superstore.de",
>    "roles": ["DEFAULT"],
>    "status": "DRAFT",
>    "timezone": "Europe/Berlin",
>    "organization": {
>      "legal_name": "SuperStore GmbH",
>      "registered_address": {
>        "line1": "Hasengarten 14",
>        "city": "Berlin",
>        "postal_code": "79341",
>        "country": "DE"
>      }
>    }
>  }'

A customer starts in DRAFT. Activate them before creating a subscription:

$curl -X POST https://test.api.solvimon.com/v1/customers/superstore-001/activate \
>  -H "X-API-KEY: <apiKey>"

📘 Via Desk: Customers → New customer.

Step 6: Create a subscription

The /init endpoint creates the subscription and its first schedule in a single call. This is the recommended way to start a subscription.

$curl -X POST https://test.api.solvimon.com/v1/pricing-plan-subscriptions/init \
>  -H "X-API-KEY: <apiKey>" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "pricing_plan_subscription": {
>      "reference": "superstore-001-sub-2024",
>      "customer_reference": "superstore-001",
>      "billing_entity_reference": "<your_billing_entity_reference>",
>      "billing_currency": "EUR",
>      "billing_time": "EXACT"
>    },
>    "pricing_plan_schedules": [
>      {
>        "pricing_plan_version_selector": {
>          "pricing_plan_reference": "<your_pricing_plan_reference>"
>        },
>        "start_at": "2024-01-01T00:00:00Z"
>      }
>    ]
>  }'

Key fields:

  • billing_time: "EXACT" — invoices are generated on the same day of the month as start_at. If the subscription starts on the 1st, invoices are always on the 1st.
  • billing_entity_reference — the billing entity issuing the invoices. Configure one under Settings → Billing entities if you haven’t already.
  • Omitting first_payment and payment_method means invoices are generated but not auto-charged. Add those fields when you’re ready to connect a payment provider.

📘 Via Desk: Customers → select customer → Subscriptions → New subscription.

Step 7: Send a usage event

Once the subscription is active, start reporting usage. Send one event per billable action — don’t pre-aggregate.

$curl -X POST https://test.api.solvimon.com/v1/ingest/meter-data \
>  -H "X-API-KEY: <apiKey>" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "meter_reference": "api_calls",
>    "customer_reference": "superstore-001",
>    "reference": "evt_20240115_001",
>    "timestamp": "2024-01-15T14:30:00Z",
>    "meter_values": [
>      {
>        "reference": "call_count",
>        "number": "1"
>      }
>    ]
>  }'

Key fields:

  • reference — a unique ID for this event. If you send the same reference twice, the second event is deduplicated. Use your internal request ID or transaction ID.
  • timestamp — when the usage occurred. Defaults to the current time if omitted.
  • meter_values[].number — the quantity. For a COUNT meter tracking individual calls, this is "1" per event.

A 200 response means the event was accepted. Events are matched to the subscription based on the customer_reference and the meter linked to the subscription’s product item.

📘 Via Desk: You can manually create events under Usage metering → Events → New event. Use this for backfills or testing.

Step 8: View the draft invoice

Solvimon generates a draft invoice for the current billing period. Check it via the invoices endpoint:

$curl "https://test.api.solvimon.com/v1/invoices?customer_reference=superstore-001" \
>  -H "X-API-KEY: <apiKey>"

Response (trimmed):

1{
2  "data": [
3    {
4      "id": "inv_xyz789",
5      "object_type": "INVOICE",
6      "status": "DRAFT",
7      "customer_reference": "superstore-001",
8      "billing_period_start": "2024-01-01T00:00:00Z",
9      "billing_period_end": "2024-02-01T00:00:00Z",
10      "total_amount": {
11        "quantity": "0.01",
12        "currency": "EUR"
13      }
14    }
15  ]
16}

The invoice stays in DRAFT until the billing period ends (or the grace period expires). During this time, new usage events continue to be added to it.

📘 Via Desk: Invoicing → Invoices. You can preview the draft invoice and see the individual line items.

What happens next

At the end of the billing period, Solvimon automatically moves the invoice from DRAFT to FINAL. When that happens:

  • A invoice.finalized webhook fires (if you’ve configured webhooks)
  • The invoice is locked and no further usage is added to it
  • If a payment method is on the subscription, the charge is attempted automatically

To set up payment collection, see Bill your first B2C customer.

Next steps