> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.solvimon.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server. # 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 the [API quickstart](/platform-guides/getting-started/onboarding-and-tutorials/api-quickstart) * A billing entity configured under **Settings → Billing entities** in [Desk](https://test.desk.solvimon.com) * `curl` or any HTTP client --- ## Overview Solvimon's primitives have a dependency order. You need each piece before you can create the next: | Step | Resource | What it does | | ---- | ----------------------------------------- | --------------------------------------------------- | | 1 | Meter + Meter Value | Defines what usage you're measuring | | 2 | Meter Value Calculation | Defines how to aggregate the usage (sum, max, etc.) | | 3 | Product Category + Product + Product Item | Defines what you sell | | 4 | Pricing Plan | Defines the price and billing terms | | 5 | Customer | Who you're billing | | 6 | Subscription | Links the customer to the pricing plan | | 7 | Usage Event | Reports actual usage | | 8 | Invoice | Generated automatically from the subscription | > **Note** > > In Desk, the [guided billing metric setup](/platform-guides/products-and-pricing/product-catalog/products-1) lets you create the meter, meter value, and calculation inline while adding a revenue item. The dependency order still applies; you're creating the same resources, only from one place. This tutorial uses the API, where each resource is created explicitly. --- ## 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. ```bash curl -X POST https://test.api.solvimon.com/v1/meter-values \ -H "X-API-KEY: " \ -H "Content-Type: application/json" \ -d '{ "reference": "call_count", "name": "Call Count", "type": "NUMBER", "status": "ACTIVE" }' ``` Response: ```json { "id": "metv_def456", "object_type": "METER_VALUE", "reference": "call_count", "name": "Call Count", "type": "NUMBER", "status": "ACTIVE" } ``` ### Create the meter ```bash curl -X POST https://test.api.solvimon.com/v1/meters \ -H "X-API-KEY: " \ -H "Content-Type: application/json" \ -d '{ "reference": "api_calls", "name": "API Calls", "status": "ACTIVE", "meter_values": [ { "id": "metv_def456", "required": true } ] }' ``` Response: ```json { "object_type": "METER", "id": "metr_abc123", "reference": "api_calls", "name": "API Calls", "status": "ACTIVE", "meter_values": [ { "id": "metv_def456", "required": true } ] } ``` ## > **Note** > > **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. ```bash curl -X POST https://test.api.solvimon.com/v1/meter-value-calculations \ -H "X-API-KEY: " \ -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: ```json { "id": "mvc_ghi789", "object_type": "METER_VALUE_CALCULATION", "reference": "api_calls_sum", "name": "API Calls Sum", "calculation_type": "SUM" } ``` 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 ```bash curl -X POST https://test.api.solvimon.com/v1/product-categories \ -H "X-API-KEY: " \ -H "Content-Type: application/json" \ -d '{ "reference": "platform", "name": "Platform" }' ``` ### Create a product ```bash curl -X POST https://test.api.solvimon.com/v1/products \ -H "X-API-KEY: " \ -H "Content-Type: application/json" \ -d '{ "reference": "api_access", "name": "API Access", "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`. ```bash curl -X POST https://test.api.solvimon.com/v1/product-items \ -H "X-API-KEY: " \ -H "Content-Type: application/json" \ -d '{ "reference": "api_calls_item", "name": "API Calls", "product_id": "", "model_type": "USAGE_BASED", "usage_based": { "meter_value_calculation_id": "mvc_ghi789" } }' ``` Then activate the product and product item: ```bash curl -X POST https://test.api.solvimon.com/v1/products/api_access/activate \ -H "X-API-KEY: " curl -X POST https://test.api.solvimon.com/v1/product-items/api_calls_item/activate \ -H "X-API-KEY: " ``` > **Note** > > **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. To create a plan via API: create the plan with [POST /v1/pricing-plans](https://docs.solvimon.com/api-docs/configuration-api/pricing-plans/post-pricing-plans), then create a version with [POST /v1/pricing-plan-versions](https://docs.solvimon.com/api-docs/configuration-api/pricing-plan-versions/post-pricing-plan-versions) and add a pricing entry with [POST /v1/pricings](https://docs.solvimon.com/api-docs/configuration-api/pricings/post-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. ## > **Note** > > **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](/api-docs/configuration-api/pricing-plans) for automation. ## Step 5: Create and activate a customer ```bash curl -X POST https://test.api.solvimon.com/v1/customers \ -H "X-API-KEY: " \ -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: ```bash curl -X POST https://test.api.solvimon.com/v1/customers/superstore-001/activate \ -H "X-API-KEY: " ``` ## > **Note** > > **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. ```bash curl -X POST https://test.api.solvimon.com/v1/pricing-plan-subscriptions/init \ -H "X-API-KEY: " \ -H "Content-Type: application/json" \ -d '{ "pricing_plan_subscription": { "reference": "superstore-001-sub-2024", "customer_reference": "superstore-001", "billing_entity_reference": "", "billing_currency": "EUR", "billing_time": "EXACT" }, "pricing_plan_schedules": [ { "pricing_plan_version_selector": { "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. ## > **Note** > > **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. ```bash curl -X POST https://test.api.solvimon.com/v1/ingest/meter-data \ -H "X-API-KEY: " \ -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. > **Note** > > **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: ```bash curl "https://test.api.solvimon.com/v1/invoices?customer_reference=superstore-001" \ -H "X-API-KEY: " ``` Response (trimmed): ```json { "data": [ { "id": "inv_xyz789", "object_type": "INVOICE", "status": "DRAFT", "customer_reference": "superstore-001", "billing_period_start": "2024-01-01T00:00:00Z", "billing_period_end": "2024-02-01T00:00:00Z", "total_amount": { "quantity": "0.01", "currency": "EUR" } } ] } ``` 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. > **Note** > > **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](/platform-guides/getting-started/onboarding-and-tutorials/bill-your-first-b2c-customer). --- ## Next steps * [Bill your first B2C customer](/platform-guides/getting-started/onboarding-and-tutorials/bill-your-first-b2c-customer) — add payment collection via Adyen or Stripe * [Webhooks](/platform-guides/for-developers/webhooks) — receive real-time notifications when invoices finalize and payments complete * [Local development setup](/platform-guides/for-developers/local-development) — receive webhooks on localhost during development