Entitlements with Custom Fields

An entitlement is what a customer is allowed to use in your product: which features are switched on, how many projects or seats they get, and so on. You can keep entitlements in MonetizeNow by adding custom fields to your products. Your application then reads those fields, through the API, for whatever the customer has bought.

This keeps billing and feature access in one place. When a customer buys, upgrades or cancels in MonetizeNow, your app can see what they're entitled to.

I want to…Go to
Understand the approachHow it works
Set it up end to endTutorial: gate a feature on what the customer bought
Read entitlements from my appGet a customer's entitlements
Stay in sync when things changeKeep entitlements up to date
Look up endpoints and field typesReference

For how to create and manage custom fields in general, see Custom Fields.


How it works

Explanation

flowchart TD
  A[Your app<br/>knows the customer] --> B[Active subscriptions<br/>for the account]
  B --> C[Product and offering IDs<br/>plus quantities]
  C --> D[Custom fields<br/>on each product]
  D --> E[Combine into<br/>the customer's entitlements]
  1. You describe each product's entitlements in custom fields on the Product object. For example, Includes Advanced Reporting is ticked on your Enterprise product and not on your Starter product.
  2. The customer buys through a quote, or you create a subscription directly. MonetizeNow records it as one or more subscriptions on the customer's account.
  3. Your app asks MonetizeNow for the account's active subscriptions. Each subscription lists its offering and its products, with quantities.
  4. Your app reads the custom fields of those products and combines them into the customer's entitlements.

Where to put entitlement fields

Custom fields live on catalog and customer objects, not on subscriptions. Pick the object that matches the decision you're making:

ObjectUse it forExample
Product (most common)What every customer gets with that productIncludes Priority Support on Gold Support
OfferingWhat a bundle or plan unlocks as a wholePlan Tier = Enterprise on the Enterprise offering
AccountOne-off exceptions for a particular customerBeta Features Opt-in ticked for Bad Wolf Media
ContractTerms agreed in a specific dealExtended Data Retention on one contract

Which field type to use

TypeGood forExampleWhat the API returns
CheckboxFeature on or offincludes_advanced_reportingtrue, false or null
NumberLimitsmax_projects = 50a number or null
Multi-selectA list of feature flagsfeature_flagsa list of option Values, for example ["time_travel_api"]
DropdownA tier or plan levelplan_tier = enterpriseone option Value or null
Custom fields for entitlements: three Checkbox fields, a Number and a Multi-select on Product, plus a Checkbox on Account

Things to know

  • A field that was never set comes back as null, not false. The product endpoints return every custom field defined for products. Treat null as "not included".
  • Changes apply to every customer on that product straight away. Your app reads the product's current values, so ticking a box on a product turns the feature on for everyone who has it. To give new customers something different without changing it for existing ones, create a new product.
  • Visibility settings don't apply to the API. A field hidden from some roles in the app is still returned by the API.
  • Quantities come from the subscription, not from custom fields. Use a subscription item's units for seat counts.

Tutorial: gate a feature on what the customer bought

Tutorial. About 20 minutes. Requires Tenant Admin (for custom fields and API keys) and someone who can call an API.

The example company sells Time Lord Platform. Customers whose plan includes Advanced Reporting should see the Vortex Analytics dashboards in your app.

Step 1: Create the custom field

  1. Go to Settings → Custom Fields and click New.
  2. Set Object to Product and Type to Checkbox.
  3. Enter the Label Includes Advanced Reporting. The API Name fills in as includes_advanced_reporting; your app will use this name.
  4. Optionally add a Tooltip, for example Unlocks Vortex Analytics dashboards. Click Save.
A new Checkbox custom field on Product called Includes Advanced Reporting

The Object, API Name and Type can't be changed after saving, and custom fields can't be deleted. Double-check them before you save.

Step 2: Set the value on your products

Open each product in Product Catalog. In Additional Fields, tick Includes Advanced Reporting where it applies, then click Save.

Time Lord Platform's Additional Fields: Advanced Reporting and Team Collaboration ticked, Priority Support not, Max Projects 50

Step 3: Create an API key

Go to Settings → API Keys and create a key for your app. Store it securely. See API Keys.

Step 4: Read the customer's entitlements

In your app, when the customer signs in (or on a schedule):

  1. Get the account's active subscriptions.

    GET https://api.monetizeplatform.com/api/accounts/{accountId}/subscriptions?billingStatus=ACTIVE
    x-api-key: YOUR_API_KEY
  2. Collect the product IDs from each subscription's subscriptionItems[].product.id, skipping items where isActive is false.

  3. Get each product's custom fields.

    GET https://api.monetizeplatform.com/api/products/{productId}
    x-api-key: YOUR_API_KEY
  4. Turn the feature on if any of the customer's products has "includes_advanced_reporting": true.

Result: customers who bought a product with Advanced Reporting see the dashboards. Everyone else doesn't. When you tick the box on another product, its customers get the feature on their next check.


How-to guides

Get a customer's entitlements

How-to

1. Identify the account. Your app needs the customer's MonetizeNow account ID (acct_…). Either store it when you create the customer, or look it up by the account's Custom ID, which you can set to your own customer ID:

GET https://api.monetizeplatform.com/api/accounts?customId=YOUR_CUSTOMER_ID
x-api-key: YOUR_API_KEY

2. Get the active subscriptions.

GET https://api.monetizeplatform.com/api/accounts/{accountId}/subscriptions?billingStatus=ACTIVE&pageSize=100
x-api-key: YOUR_API_KEY

From each subscription in content, use:

FieldWhat it gives you
offering.idThe offering, if you keep entitlement fields on offerings
subscriptionItems[].product.idEach product in the subscription
subscriptionItems[].unitsThe quantity, for example seats
subscriptionItems[].isActiveSkip items where this is false
billingStatusACTIVE, PENDING (starts later), SUSPENDED or CANCELED

Results are paged: pass currentPage (it starts at 0) and pageSize. The response's totalPages tells you whether there's more.

Important: the products and offering embedded in a subscription response don't include custom field values. Their customFields is always empty, {}. Always read custom fields from the product or offering endpoints in the next step.

3. Read the custom fields.

  • Products:
    • GET /api/products/{productId} for one product, or
    • GET /api/products?pageSize=100 to load the whole catalog once and cache it.
  • Offerings: GET /api/offerings/{offeringId}.

The values are in customFields, keyed by API Name:

{
  "id": "prod_tlp01",
  "name": "Time Lord Platform",
  "productType": "ADVANCE",
  "status": "ACTIVE",
  "customFields": {
    "includes_advanced_reporting": true,
    "includes_priority_support": null,
    "includes_team_collaboration": true,
    "max_projects": 50,
    "feature_flags": ["time_travel_api", "regeneration_backups"]
  }
}

4. Combine them. A customer with several products needs one answer per entitlement. Common rules:

Field typeCombine as
CheckboxEntitled if any product is true
Number (limits)The highest value, or the sum if limits stack (for example add-on packs)
Multi-selectThe union of all lists
Dropdown (tier)The highest tier, in an order your app defines

Then apply any Account or Contract custom fields as overrides.

Keep entitlements up to date

How-to. Requires Tenant Admin to set up webhooks.

Calling the API on every page load is slow. Instead, cache each customer's entitlements and refresh them when something changes. Set up a webhook in Settings → Webhooks for these events:

EventRefresh
subscription.created, subscription.updatedThe entitlements of that subscription's account
contract.created, contract.updatedThe account on the contract (new deals, amendments and renewals)
product.updatedYour cached product catalog, then every account that has the product
offering.updatedYour cached offering, if you use offering fields
account.updatedThe account, if you use account fields

As a safety net, also refresh each customer's entitlements on a schedule, for example nightly. See Webhooks.

Give one customer an exception

How-to

  1. Create a custom field on Account (for example the Checkbox Beta Features Opt-in).
  2. Tick it on that customer's account.
  3. In your app, after combining product entitlements, turn the feature on if the account field is true.

Use a Contract field instead when the exception is tied to a specific deal and should end with it.


Reference

API base URLs and authentication

RegionBase URL
UShttps://api.monetizeplatform.com
EUhttps://api-eu.monetizeplatform.com

Send your API key in the x-api-key header. Use the base URL for your tenant's region: the wrong region returns 401 or 403.

Endpoints used on this page

EndpointReturns custom fields?API reference
GET /api/accounts?customId=…Account fields, in customFieldsGet accounts
GET /api/accounts/{accountId}/subscriptionsNo: embedded products and offerings have no valuesGet subscriptions by account
GET /api/products/{productId}YesGet product by ID
GET /api/productsYes, for each productGet all products
GET /api/offerings/{offeringId}Yes, the offering's own fields. Products listed inside it have no values.Get offering by ID

Custom field values in the API

TypeJSON valueNot set
Checkboxtrue / falsenull
Numbernumbernull
Single Line Textstring (up to 255 characters)null
Dropdownthe option's Value (not its Label)null
Multi-selectlist of option Valuesnull
Date"YYYY-MM-DD"null

Related


Did this page help you?