Usage Rating Setup Implementation Guidance
Purpose
Provides CX Subscriptions implementation guidance for the Usage Rating Setup functional area.
When to Use
Use this functional-area skill after Subscriptions scope is confirmed and the project needs guidance for Usage Rating Setup prerequisites, balance design, entitlement design, validation checkpoints, or an approved REST/Data Loader route.
Execution Controls
This package is advisory until a task selects an execution route. Route all Fusion
REST calls through core.fusion-api.rest-api-client, all Data Loader artifact and
load operations through core.data-loader, and setup-data artifact validation
through shared.validation.setup-data-validator.
Preflight Checks
Before any side effect, confirm the selected environment, required privileges, catalog/task support, exact object identity, dependency readiness, and payload or workbook shape. Generate and validate local artifacts before upload. Immediately before a REST create, update, activation, upload, or load initiation, present the exact target, operation, and immutable payload or artifact and obtain explicit approval. Do not retry an uncertain or failed live write automatically.
Diagnostics and Redaction
For input, catalog, authorization, transport, Fusion API, artifact-persistence, or approval failures, stop and record the failure class, message, recommended action, environment, artifact references, and available request or process identifiers in the project workspace. The core client may refresh a cached OAuth token once after HTTP 401 or 403; all other retry behavior follows the selected core skill.
Never print or persist credentials, access tokens, token caches, private keys, tenant secrets, wallet files, full base64 payloads, or sensitive customer data in skill output, diagnostics, or project artifacts.
Catalog Metadata
- Pillar:
CX - Offering:
Subscriptions(CUSTOM_SUBSCRIPTIONS) - Functional area / Setup Object:
Usage Rating Setup(CUSTOM_USAGE_RATING_SETUP)
Setup Tasks
- Manage Balance Codes (
CUSTOM_MANAGE_BALANCE_CODES) - Manage Balance Profiles (
CUSTOM_MANAGE_BALANCE_PROFILES) - Manage Usage Entitlement (
CUSTOM_MANAGE_USAGE_ENTITLEMENT)
Request Routing
Usage Rating Setup begins only after its upstream commercial and product configuration is defined. The following prerequisite objects are outside this functional area and are advisory dependencies, not Usage Rating Setup tasks:
- Create the applicable Unit of Measure Class and Unit of Measure.
- Create the required one-time, recurring, and usage charges.
- Create the rate plan with its charges and defined values.
- Create the subscription item or product so the entitlement plan can be associated to it.
For a subscription that originates in Order Management, the opt-in Integrate Order Management with Subscription Management to Process Subscriptions is also required. Treat the opt-in as a prerequisite confirmation. Do not assume it is enabled or enable it as part of Usage Rating Setup guidance.
Do not route a charge-definition, rate-plan, item, product, or UOM create/update request to a Usage Rating Setup task. Identify it as a prerequisite and retain Usage Rating Setup in advisory mode until the dependency is confirmed.
Route every Usage Rating Setup request whose primary object is a Balance Code to Manage Balance Codes, including create, update, activation, lookup, and Data Loader workbook requests.
Route every Usage Rating Setup request whose primary object is a Balance Profile to Manage Balance Profiles (the Manage Balance Profile skill), including create, update, activation, lookup, and Data Loader workbook requests.
Route every Usage Rating Setup request whose primary object is a Usage Entitlement, Entitlement Plan, or Entitlement Assignment to Manage Usage Entitlement, including create, update, activation, lookup, list, and Data Loader workbook requests.
Route a request for Usage Rating, Consumption Plan, Allowance, or another Usage Rating Setup object not covered above to its dedicated task skill in this functional area when one is present in the current setup-task catalog. Do not silently map it to Balance Codes, Balance Profiles, or Manage Usage Entitlement. If no dedicated task skill is available, retain it at the Usage Rating Setup functional-area level and report the routing gap before execution.
Prerequisite Confirmation Gate
Before advising a Usage Rating Setup design that depends on a commercial plan, confirm the prerequisite configuration with the user. Do not infer a UOM, charge, rate-plan amount, or item/product from a plan name.
Record prerequisite confirmations as design inputs. If any prerequisite is unconfirmed, provide the outstanding-input list and stop at advisory guidance; do not prepare a Fusion payload, workbook, import, or external operation.
Balance Code UOM Resolution
Before preparing or executing a quantity-balance-code payload, resolve the exact approved UOM record through the selected read-only endpoint. Use the UOM display value confirmed in the project design inputs; do not substitute an example value:
/fscmRestApi/resources/latest/unitsOfMeasure?limit=500&fields=UOMCode,UOMClass,UOMClassCode,UOMClassName,UOM,Description&onlyData=true&orderBy=CreationDate:desc&q=UOM='<approved UOM display value>'
Require exactly one matching row with a nonblank UOMCode. Set
BalanceUnitofMeasureCode from the returned UOMCode only. Never pass the display
value UOM as BalanceUnitofMeasureCode. Treat no match, multiple matches, a blank
UOM code, authorization, transport, or Fusion API failure as a blocker; do not
prepare a create payload or retry automatically.
Optional Post-Setup Verification
After the opt-in, item, charge definitions, price list, and rate plans have been
created and activated through their approved workflows, a user may request a read-only
verification. Use core.fusion-api.rest-api-client and the configured Fusion
environment; do not infer completion from design inputs or perform any mutation.
For each approved charge definition, issue an exact-name
GETto/crmRestApi/resources/latest/subscriptionChargeDefinitionswithq=Name='<approved charge name>', requestingName,ChargeDefinitionCode, andChargeDefinitionId. Require exactly one row and the expected code from the approved design inputs.Project input Required value Charge name Approved charge name Expected charge-definition code Approved charge-definition code For each approved rate plan, issue an exact-name
GETto/fscmRestApi/resources/latest/ratePlans/withq=RatePlanName='<approved rate plan name>'. Require exactly one row.Report each result as present, absent, ambiguous, or lookup failed. Persist the validation result and a skill-run record under the active project workspace. A missing, ambiguous, authorization, transport, or Fusion API failure blocks any downstream build step; do not retry automatically except for the shared client's one allowed OAuth refresh after HTTP 401 or 403.
Inputs
implementation_objectiveproject_contextusage_rating_setup_scopeusage_rating_setup_requirements
Outputs
functional_area_setup_planconfiguration_guidancevalidation_checkpointsskill_run_recordtoken_usage_record
Implementation Notes
Use the generated setup-task metadata files for task-level planning and sequencing. Track token usage for any generated project artifact or skill-run record using the manifest policy.
For a Minutes Balance Code request, follow the reuse-or-create workflow in Manage Balance Codes: return an exact matching validated project workbook or existing Fusion balance code first, and generate a fresh Data Loader workbook only after the customer explicitly requests one. Never prepare a duplicate-create source for an existing balance-code identifier.