In this section · 3 articles

Monetization permissions and server settings

Every Monetization permission and what it allows, the server settings for grace days, retries and batch sizes, the scheduled tasks that renew and expire subscriptions, and what the health check reports.

Applies to
Monetization 3.0 and later
Who can do this
Administrator, Platform owner
On this page

Monetization has no settings panel. What a person can do comes from their permissions. How long a subscription waits for payment and how often a failed renewal is retried come from your Laramin's server configuration.

Permissions

All keys start with feature.mon.. In the role editor they're in five groups. Most resources have the seven standard actions: list, view, create, edit, delete, restore and remove (delete for good). Give them with a role. See Give someone a role.

Monetization brings no roles. Create one for each team that works with it and give it the permissions below. See Create a role.

The role editor with the Monetization module expanded, showing its five permission groups: Features & Entitlements, Plans & Pricing, Promotions & Credits, Regions, and Subscriptions & Renewals.

Regions

ResourceActionsAllows
regionThe seven standard actionsRegions: adding, changing, deleting and restoring regions.
region_contextThe seven standard actionsA region's Currencies & languages. Kept apart from region, so someone who can read regions can't change which currencies a region trades in.

Features & Entitlements

ResourceActionsAllows
featureThe seven standard actionsFeatures. Changing a feature changes what it means on every plan that uses it.
feature_groupThe seven standard actionsFeature groups.

Plans & Pricing

ResourceActionsAllows
planThe seven standard actionsPlans: the plan's own details.
planpublishPublish: puts a plan on sale.
planarchiveArchive: takes a plan off sale.
planduplicateDuplicate. In Monetization 3.0.0 it fails with a server error and copies nothing.
plan_pricingThe seven standard actionsA plan's Pricing. Kept apart from plan.edit, because a wrong price is money charged wrongly.
plan_featureThe seven standard actionsA plan's Entitlements: what a customer receives.
plan_offeringThe seven standard actionsA plan's Bundled offerings.
offering_pricingThe seven standard actionsOffering pricing.

In Monetization 3.0.0 anyone with feature.mon.plan.create or feature.mon.plan.edit can also put a plan on sale by setting its Status to Active on the plan form. That skips both the publish permission and the check that the plan has a price.

Subscriptions & Renewals

ResourceActionsAllows
subscriptionlist, viewSubscriptions: the list. A subscription has no page of its own in 3.0.0.
subscriptioncancelCancel: stops renewal at the end of the paid period.
subscriptionresumeResume: undoes a cancel before the period ends.
subscriptionend_nowEnd now: ends access at once. Kept apart from cancel, because it takes away a period the customer already paid for.
renewallist, viewRenewals. There's no permission to retry or change one, because no one can.

subscription also has create, edit, delete, restore and remove. They allow nothing: subscriptions have no form and can't be deleted.

Promotions & Credits

ResourceActionsAllows
promotionThe seven standard actionsPromotions. A promotion that has been redeemed can't be removed for good.
promotion_redemptionlist, viewA promotion's Redemptions.
promotion_redemptionrevokeRevoke on a redemption. There's no delete, because redemptions are what every limit is counted against.
product_creditlist, view, create, editProduct credits: granting a credit, and correcting its reason, expiry or unit.
product_creditrevokeRevoke: withdraws what's left of a credit.

If your Laramin had these screens under CentralApp before, the old feature.cap.* permissions were renamed to these in place, so every role keeps what it had.

Server settings

These are set in your Laramin's server configuration (its .env file) by whoever hosts it. They apply to every business.

SettingWhat it doesDefault
MONETIZATION_RENEWAL_GRACE_DAYSThe least number of days a subscription keeps working after its period ends without a successful renewal. Monetization raises it so it always outlasts the retry schedule: with the default schedule, the grace is 17 days.7
MONETIZATION_RECONCILE_AFTER_MINUTESHow old an unanswered renewal must be before Monetization asks Billing whether its invoice was paid.15
MONETIZATION_RENEWAL_BATCHThe most subscriptions one renewal run handles. The rest wait for the next run, and a warning is written to the server log.500
MONETIZATION_DEFAULT_CURRENCYThe currency an amount is shown in when its record doesn't name one. Every price you enter names its own currency.USD

The retry schedule

When a renewal fails, Monetization retries it after a list of delays in days. The default is [1, 3, 5, 7]: four retries over 16 days, then the subscription ends. The number of entries is the number of retries. There's no separate limit.

This list is set in Monetization's configuration file (monetization.dunning.retry_days), not in .env. Ask whoever hosts your Laramin to change it before you go live if it doesn't match your policy. See How subscriptions and renewals work.

Scheduled tasks

Monetization adds five tasks to your Laramin's scheduled jobs. They run only while scheduled jobs run. Developer Tools › Scheduler shows when each job last ran. If they don't run, see Scheduled jobs don't run.

TaskRunsDoes
mon:reconcile-renewalsEvery 15 minutesAsks Billing about renewals still waiting, and completes those whose invoice was paid, in case the payment notice never arrived.
mon:renew-subscriptionsDailyStarts a renewal for every subscription whose renewal date has passed.
mon:run-dunningDailySchedules retries for failed renewals, and ends subscriptions whose retries have run out.
mon:expire-subscriptionsDailyMarks subscriptions whose access has ended as Expired, including those whose grace ran out without a renewal.
mon:expire-product-creditsDailyMarks product credits whose expiry has passed as Expired. An expired credit can't be spent even before this runs.

Each task works through each business in turn. Rows that belong to a business that has been closed are skipped and a line is written to the server log.

Health check

Laramin checks every enabled add-on every five minutes, and Addon Management shows Monetization as Unhealthy when one of these is true. See Add-on statuses.

Message starts withMeans
Monetization is enabled but its tables do not existMonetization's database changes haven't run. Contact whoever hosts your Laramin.
… unit type(s) are stored on features but implemented by nothingA feature's Unit type isn't one Monetization knows, so every value entered for it on a plan is refused. See Define features and feature groups.
… published plan(s) have no active priceA plan is on sale with nothing to buy. Add a price, mark it Enterprise, or archive it. See Create and publish a plan.
… renewal(s) could not be charged at allRenewals are Blocked, almost always because Billing isn't installed or enabled. Nothing was canceled, and the subscriptions are running on their grace. See A subscription didn't start or renew.

When it's healthy, the check also reports how many plans are active, how many subscriptions are active and how many are past due.