Retrieve discount-inclusive MRR through the API
The customer API now exposes current and pending MRR including time-limited discounts. The new effectivemrrbycurrency and effectivependingmrrbycurrency fields correspond to the "MRR incl. discounts" and "Pending MRR incl. discounts" columns in the CSV export.
The customer API now exposes current and pending MRR including time-limited discounts. The new effective_mrr_by_currency and effective_pending_mrr_by_currency fields correspond to the “MRR incl. discounts” and “Pending MRR incl. discounts” columns in the CSV export.
Current and pending MRR remain separate: Pending MRR covers subscriptions with a future start date, an active trial, or an active pause. All four API fields are grouped by currency and use the smallest currency unit, such as øre or cents.
Historical background - August 2024 to September 2026
The MRR API began with current metrics and later expanded with pending values, discounts, intervals, and scheduled changes. A response for a specific subscription is more relevant than a plan catalog price because the subscription can have its own price, currency, trial, or discount.
When an integrator changes a trial, discount, or renewal interval, read the updated subscription back and distinguish a change that applies now from a scheduled change. Use UUIDs, pagination, and the amount unit documented by OpenAPI. See the public API and webhooks guide (Markdown file, AI agent-friendly).
From read to change to read-back
Start with GET /api/v1/subscriptions/{uuid} using the fictional, nonexistent UUID 00000000-0000-4000-8000-000000000003 in a test example. Store the current price, pricing type, interval, trial, and available_price_change_dates before sending a change. Send only the action you intend, then read the subscription response back. The API returns the updated subscription and may report the actual effective date in meta.effective_date.
Trial
Use PUT /api/v1/subscriptions/{uuid}/trial with { "end_date": "2026-10-15" } for an existing, unlocked trial. The end date must be after the trial start. A subscription without a trial, or a trial whose transaction has already been invoiced or charged, returns 422; this call does not create a trial.
Discount
Use POST /api/v1/subscriptions/{uuid}/discounts with a documented discount type. A percentage such as 14.29 means 14.29 percent, while a fixed discount uses the smallest currency unit, such as 5000 = 50.00. The discount window must start on an unlocked period and cannot overlap another pending discount. Usage-based subscriptions support percentage discounts, while a fixed discount is rejected.
Interval and price
PUT /api/v1/subscriptions/{uuid}/interval with, for example, { "interval": 3 } uses intervals configured on the plan and takes effect from the next upcoming period. PUT /api/v1/subscriptions/{uuid}/price takes price for flat-rate or unit_price for license-based subscriptions; do not mix the fields. Price changes apply to the next period by default, or to a valid effective_date, while usage-based and tiered prices follow their own pricing rules.
A scheduled change is not active yet. If a period is invoiced or locked, the change is placed on an allowed future date and future transactions are rebuilt. Use the subscription response and scheduled-change endpoint to show what is planned, and DELETE /api/v1/subscriptions/{uuid}/scheduled-changes/{scheduledChangeUuid} to remove a specific pending change when the contract permits it.
Frequently asked questions
Why is API MRR different from the plan price? MRR follows the specific subscription with its discount, trial, currency, and status; the plan catalog price is only the default.
Why did my price not become active immediately? A locked or already invoiced period moves the change to an allowed future date.
Why is a discount rejected? Check type, percentage/currency unit, unlocked start date, and overlap with other discounts.
Can I change the interval on a tiered subscription? Use the tier-aware contract and price for the subscription’s selected tier; do not substitute a raw renewal-interval row.
The people and AI helpers behind the updates
Bo Møller and Emil Højbjerg are the primary developers behind Alunta. They spend most of their time coding, so they have delegated the wording of these explanations to our AI helpers.
The AI helpers write from the updates we have deployed to the product. Bo and Emil are behind the changes and remain responsible for ensuring the information reflects what was actually released.
