# Credit Management

Credit management is the One Platform capability used to configure prepaid product metrics, assign an initial credit balance to a contract item, and manage the resulting customer portfolios.

The complete lifecycle starts with the product metric configuration and continues through billing model and SKU setup, contract item creation, balance monitoring, customer allocations, and movement history.

## Main Capabilities

| Capability | Description |
|  --- | --- |
| Credit metric definition | Mark an incremental product metric as credit-enabled. |
| Credit billing model | Create a billing model that lets a contract item select one or more credit metrics. |
| SKU association | Make the credit billing model available to the SKUs that can use it. |
| Initial balance | Define a positive initial quantity for every selected credit metric. |
| Credit summary | Review received, assigned, consumed, and remaining credits. |
| Portfolio management | Allocate, remove, recover, and transfer credits within an eligible customer hierarchy. |
| Movement history | Search credit operations and inspect their technical details. |


## Configuration Flow

Configure credit products in this order:

1. Create the product and its credit-enabled metrics.
2. Create a billing model of type **Credit**.
3. Associate the billing model with one or more SKUs.
4. Add a contract item, select its credit metrics, and enter an initial quantity for each one.
5. Complete the contract lifecycle and verify that the item is active.
6. Open the customer **Credits** tab to monitor or manage the resulting portfolios.


Configuration order matters
The product metric configuration must exist before a credit billing model can be used on a contract item. The credit metrics, initial quantities, product, SKU, billing model, and parent item of a credit contract item cannot be changed after creation. Create a new item if the commercial credit configuration must change.

## Define Credit Metrics

A product metric describes the unit whose consumption reduces a credit balance. Credit metrics use the same product metric catalog as consumption monitoring, with these additional rules:

- `type` must be `Incremental`;
- `isCredit` must be `true`;
- the metric identifier must be unique within the product;
- the English label is required; other supported translations are optional;
- only one product metric configuration can be created for each product.


Product metric configuration is currently an administrative API prerequisite; it is not edited from the web application. Create it with `POST /v1/product-metrics` after the product has been registered.

The following example defines two independent credit balances for one product:

```json
{
  "productId": "your-product-id",
  "attributes": [],
  "metrics": [
    {
      "id": "ltv-signature",
      "label": {
        "en": "Signature Service with LTV and X-L"
      },
      "type": "Incremental",
      "unit": {
        "en": "signatures"
      },
      "aggregationLevel": "Daily",
      "visible": true,
      "isCredit": true,
      "attributes": []
    },
    {
      "id": "ltv-extension",
      "label": {
        "en": "Signature Extension Service (LTV and X-L)"
      },
      "type": "Incremental",
      "unit": {
        "en": "extensions"
      },
      "aggregationLevel": "Daily",
      "visible": true,
      "isCredit": true,
      "attributes": []
    }
  ],
  "counterMetrics": [],
  "aggregationsIntervalDays": 1
}
```

Use `GET /v1/product-metrics/products/{productId}` to verify the saved configuration. Creating metrics requires the metric creation permission; reading them requires the metric view permission.

One balance per metric
A contract item can select multiple credit metrics. One Platform keeps a separate balance, consumption total, customer allocation, and movement history for every contract item and metric pair.

## Create a Credit Billing Model

Open **Business Assets > Billing models**. The list distinguishes **Standard** and **Credit** billing models.

Select **Create billing model**, enter its name and description, and choose **Credit** as the type.

The billing model type is fixed after creation. When a Credit billing model is created, One Platform automatically adds the protected `creditMetrics` parameter with these properties:

| Property | Value |
|  --- | --- |
| Type | ProductMetric |
| Required | Yes |
| Multiple values | Yes |
| Value source | Credit-enabled metrics of the contract item's product |


The parameter lets an operator select one or more metrics while creating the contract item. Its structural properties cannot be removed or changed, although its display labels, placeholder, order, and group can be maintained.

### Associate SKUs

Open the **SKU** section of the billing model and add each SKU that can use it.

A billing model can be associated with multiple SKUs. The SKU association makes the model available during item creation; it does not permanently bind a SKU to a particular credit metric. The operator selects the applicable credit metrics on the contract item.

## Create a Credit Contract Item

Create or open the customer contract from **Business Assets > Contracts**, then add an item using a SKU associated with the Credit billing model.

During the item wizard:

1. select the product and SKU;
2. select one or more values in **Credit metrics**;
3. enter a positive **Initial credits** quantity for every selected metric;
4. review the item and complete its creation.


The example contract for **3G SOLUCIONES MOVILIDAD SOCIEDAD LIMITADA** uses the `Uanataca LTV Credits` billing model and selects both `ltv-extension` and `ltv-signature`. Open the item details to verify the separate initial quantities, billing model, and selected metrics.

### Initial Credit Rules

| Contract type | Initial credit behavior |
|  --- | --- |
| Direct | Enter a positive initial quantity for every selected metric. |
| Distribution | Enter a positive initial quantity for every selected metric; credits can then be assigned to eligible customers. |
| Resell | Enter a positive quantity funded by the referenced parent item for the same metric. |
| Indirect | Do not enter initial credits; the item inherits its credit metrics and receives credits from its parent. |


The general item **Quantity** field does not set the credit balance. Only the per-metric initial credit values create the opening credit movements.

Validate every selected metric
The set of initial-credit keys must exactly match the selected credit metrics. Missing quantities, additional metrics, zero, or negative values prevent item creation.

## Open a Customer Credit Portfolio

Go to **Consumers > Customers**, open the customer, and select the **Credits** tab.

The **Summary** view displays one card for each active contract item and credit metric. Use the contract type, item, product, and metric filters to find the required portfolio.

Each balance is calculated independently:

```text
Remaining = Received - Assigned to customers - Own consumption
```

| Value | Meaning |
|  --- | --- |
| Received | Credits funded on the item by an initial allocation, parent portfolio, or later top-up. |
| Assigned to customers | Credits currently allocated to child customer items. This value is shown for Distribution and Resell portfolios. |
| Own consumption | Consumption recorded against the managing Distribution or Resell item's own Business Relation. |
| Consumed | Consumption recorded against a Direct or Indirect item. |
| Remaining | Credits still available for consumption or further allocation. |


Customer consumption is not subtracted from the managing portfolio a second time: its allocation is already included in **Assigned to customers**.

Only active items of type Direct, Indirect, Distribution, or Resell are included. Draft, Final, Expired, and Cancelled contracts do not produce portfolio cards. A card can exist before consumption is recorded; when no Business Relation is available, consumption remains zero.

## Manage Distribution and Resell Portfolios

Distribution and Resell cards expose customer portfolio actions and a **Customer details** section. Distribution cards also support administrative assignment and removal of credits without deducting them from a legal entity.

An eligible customer item must:

- be an Indirect or Resell child of the exact managing contract item;
- use the same product and legal entity;
- contain the same credit metric;
- be active and visible in the current commercial scope.


Direct items are not recipients of portfolio operations.

### Portfolio Operations

| Operation | Direction | Maximum amount |
|  --- | --- | --- |
| Assign credits | External funding to a Distribution item | Positive amount accepted by the operation. |
| Remove credits | Distribution item to external funding | The Distribution item's remaining credits. |
| Top up | Managing item to one eligible customer | The managing item's remaining credits. |
| Recover | One eligible customer to the managing item | The lower of the customer's remaining credits and the amount previously funded by that manager. |
| Transfer | One eligible customer to a sibling under the same manager | The lower of the source customer's remaining credits and its balance with that manager. |


Select **Top up** next to a customer, enter the quantity, and confirm. The dialog displays the maximum available amount before the operation.

Select **Transfer** to move available credits between two eligible sibling customers. A transfer changes the two customer balances but does not change the managing portfolio's total assigned amount.

Actions are hidden or disabled when the user lacks contract management permissions, the source has no transferable balance, no eligible destination exists, or the item is outside the active commercial hierarchy.

## Review Movement History

Open the **Movements** tab to review Top-up, Recovery, and Transfer operations. Filters are available for customer, product, metric, and operation type.

Open a movement to inspect its source, destination, managing portfolio, quantity, timestamp, and technical identifiers.

Movement history comes from the credit ledger. Consumption reduces the available balance but does not create a Top-up, Recovery, or Transfer row. Historical names and descriptions reflect the current catalog data associated with the stored identifiers.

## Access and Troubleshooting

| Situation | Check |
|  --- | --- |
| A metric is missing from Credit metrics | Confirm that it belongs to the selected product, uses type `Incremental`, and has `isCredit: true`. |
| A billing model is unavailable | Confirm that it is active and associated with the selected SKU. |
| Item creation is rejected | Verify that every selected metric has exactly one positive initial quantity and that the parent item has sufficient credits when applicable. |
| A portfolio card is missing | Confirm that the item is active, the contract is in an included state, and the user can access its commercial scope. |
| Consumption remains zero | Verify that the item has a coherent Business Relation for the same product, legal entity, and metric. |
| A customer action is unavailable | Confirm the parent-child relationship, matching product/legal entity/metric, remaining balance, and user permissions. |
| An operation result is uncertain | Refresh the portfolio and movement history before repeating the operation. Reuse the same operation identity when retrying through an integration. |


Viewing customer credit portfolios follows consumption-view permissions. Creating or changing credit movements requires the relevant contract management permissions. Organization users can only see and manage portfolios available through their ownership or commercial path.

## Related Sections

- [Customer Management](/products/oneplatform/one-platform-knowledge-center/03-products-and-modules/01-web-platform/customer-management)
- [Contracts Management](/products/oneplatform/one-platform-knowledge-center/03-products-and-modules/01-web-platform/contracts-management)
- [Consumptions Monitoring](/products/oneplatform/one-platform-knowledge-center/03-products-and-modules/01-web-platform/consumptions-monitoring)
- [Key Concepts - Contracts](/products/oneplatform/one-platform-knowledge-center/01-get-started/02-key-concepts/key-concepts#contracts)