Billing Rules Registration

Use billing rules to identify billable transactions so that they can be mapped to SKUs defined in Salesforce.

📘

NOTE

Billing Rules registration and approval are required prior to the product approval for production usage.

🚧

Additional Information

For more information, see Product Configuration.

Billing Rules Workflow

Billing Rules registration process follows the sequence listed below:

Billing Setup and Approval WorkflowBilling Setup and Approval Workflow

Billing Setup and Approval Workflow

  1. Create the billing rule
    An EPC integration developer can create a billing rule record by calling the POST API (/v2/products/:id) and pass the billing information. The POST will always create a record in DRAFT status.

  2. When the rule is in DRAFT mode, EPC integration developer needs to contact the IMT Relationship Manager/Solutions Architect to initiate a review and approval of their submission.

📘

NOTE

Transactions during DRAFT mode are ignored/not considered for billing

  1. Contact your IMT Relationship Manager/Solutions Architect to initiate a review of your submission

  2. When the review is completed, the rule is APPROVED if all the terms of your contract with IMT are satisfied.

📘

NOTE

A billing rule cannot be modified once it is APPROVED/REJECTED/DEPRECATED. You will need to create a new billing rule in DRAFT which will follow the process for approval/rejection. Once a billing rule is approved, any existing billing rules in APPROVED state will be marked as DEPRECATED.

Create/Update Billing Rules

The following operations are supported for creating/updating a billing rule:

POST /v2/products/:id/billingRules
Content-Type: application/json
Creates a new billing rule for a given product. There can only be one billing rule in DRAFT state.

{
      "transformations": [   // Transform definitions that qualify certain transaction states into billable SKU's, evaluated in order
        {
          "sku": "SKU1",    // Target SKU for this transform definition
          "transaction": {
            "requestType": "Asset Verification", // Qualifying transaction request type
            "status": "completed", // Qualifying transaction status
            "scope": "borrower", // Qualifying transaction scope
            "options": {
               "x": 10,
               "y": "",
               "z": null,
               "complexTypeAllowed": {}
            }
          },
          "groupingRules": [ // Grouping rules that qualify related transactions to be recorded with an alternative SKU, evaluated in order
            {
              "ignore" : true, // Ignoring will result in not tagging the transaction as billable
              "groupAs": "SKU2", // Target SKU
              "period": 30  // Optional condition for qualifying number of days
            }
          ]
        },
        {
          "sku": "SKU2",    // Target SKU for this transform definition
          "transaction": {
            "requestType": "Refresh", // Qualifying transaction request type
            "status": "completed", // Qualifying transaction status
            "scope": "borrower" // Qualifying transaction scope
          }
        }
      ]
    }

Billing rules/setup

Parameter

Description

status

Status of this specific rule set

transformations

Transform definitions that qualify certain transaction states into billable SKUs, evaluated in order

sku

Target SKU for this transform definition
NOTE: If you are unsure of which SKU to register for your billing, contact your ICE Relationship Manager.

transaction

Entity containing attributes of the transaction. It contains the requestType, status and options of the given transaction.
requestType: Qualifying transaction request type
status: Qualifying transaction status
scope: Qualifying transaction scope
options: Qualifying transaction options

groupingRules

A set of transactions occurring on a given loan for the same product in a given duration are grouped together by a sku. Grouping rules are applied when a transaction is created/updated on a loan within a period (number of days, max value 100) defined in the grouping rule. As part of the grouping rule definition the matching result can either be mapped to another SKU or be specified to be ignored.

For example: If a credit transaction is ordered on a new loan and if the billing rule matches, sku defined in the billing rule is applied. If there is a grouping rule defined, and another transaction is created on the same loan for the same provider in the same duration mentioned in period, sku defined in the grouping rule is applied. Or instead of groupAs, ignore = true is specified than the matching transaction will not be considered as billable

Options

Optional attribute of the billing rule and when present, is applied on the options in the transaction.

📘

NOTE

If you need help with defining your billing rule, reach out to your ICE Relationship Manager.

GET /v2/products/:id?view=billingrule

Returns the list of all billing rules (draft and approved) along with other product details. A query parameter for view=billing will also be supported to only view the billing rules defined for a product.

{
    "id": "e1cca3a5-03ba-41b2-a525-68067d798ee5",
    "partnerId": "cab43a26-d284-11ea-87d0-0242ac130003",
    "productId": "d007f45e-d284-11ea-87d0-0242ac130003",
    "productName: "Test flood product",
    "status": "Draft/Approved/Rejected",
    "billingRules": [
    {
      "status": "draft",
      "transformations": [
        {
          "sku": "SKU1",
          "transaction": {
            "requestType": "Basic Flood",
            "status": "completed",
            "scope": "loan"
          }
        },
        {
          "sku": "SKU2",
          "transaction": {
            "requestType": "Life of Loan",
            "status": "completed",
            "scope": "loan"
          },
          "groupingRules": [
            {
              "ignore": true,
              "period": 30
            }
          ]
        }
      ]
    }
  ]
}

PATCH /v2/products/:id/billingRules/:id
Content-Type: application/merge-patch+json
Updates an existing billing rule

{
     "status": "draft|approved|rejected",
     "transformations": [
       {
         "sku": "SKU1",
         "transaction": {
           "requestType": "Basic Flood",
           "status": "completed",
           "scope": "loan"
         }
       },
       {
         "sku": "SKU2",
         "transaction": {
           "requestType": "Life of Loan",
           "status": "completed",
           "scope": "loan"
         },
         "groupingRules": [
           {
             "groupAs": "SKU3",
             "period": 30
           }
         ]
       }
     ]
   }

Retrieving billable records

Partners have the ability to look up all the billable transactions for a specified period of time. They can view:

  • The complete data for a billable period or
  • A summary of the information, such as the number of SKUs that have been charged/identified as billable transaction for a particular SKU type

POST /v2/billing?view=summary
Returns the quantity for each SKU based on a given search condition

{
    "startCreated": "2020-07-01T20:44:03Z",
    "endCreated": "2020-10-09T01:42:16Z",
    "skus": ["SKU2","SKU3"],
    "environment": "sandbox",
    "partnerIds": ["007001","009001"],
    "productIds": ["2984725b-6237-468a-ad18-fff368b2f6ec"]
}
[
  {
    "product": {
      "id": "2984725b-6237-468a-ad18-fff368b2f6ec",
      "name": "Life of Loan",
      "partnerId": "007001"
    },
    "sku": "123-121-121",
    "quantity": 1000
  },
  {
    "product": {
      "id": "2984725b-6237-468a-ad18-fff368b2f6ec",
      "name": "Data Verify",
      "partnerId": "007001"
    },
    "sku": "333-121-124",
    "quantity": 500
  }
]

POST /v2/billing?view=complete
Returns detailed billing information for a given search condition.

{
    "startCreated": "2020-07-01T20:44:03Z",
    "endCreated": "2020-10-09T01:42:16Z",
    "skus": ["SKU2","SKU3"],
    "environment": "sandbox",
    "partnerIds": ["007001","009001"],
    "productIds": ["2984725b-6237-468a-ad18-fff368b2f6ec"]
}
[
    {
        "sku": "SKU2",
        "quantity": 1,
        "created": "2020-10-07T01:05:04Z",
        "transaction": {
            "id": "f6c8d531-a6f1-4df7-91a9-698265675fc0",
            "referenceId": "000901",
            "clientId": "urn:elli:client:DEBE11170913",
            "environment": "sandbox",
            "created": "2020-10-09T00:45:17Z",
            "updated": "2020-10-09T01:05:03Z",
            "entityRef": {
                "entityId": "urn:elli:encompass:DEBE11170913:loan:83138afd-3c04-400c-ab54-db8b03d6df34",
                "entityType": "urn:elli:encompass:loan"
            },
            "status": "completed",
            "request": {
                "type": "Life of Loan"
            },
            "response": {
                "referenceNumber": "000901"
            }
        },
        "product": {
            "id": "2984725b-6237-468a-ad18-fff368b2f6ec",
            "name": "Flood-DataVerifyCBC_204142861626554",
            "partnerId": "007001"
        }
    },
    {
        "sku": "SKU3",
        "quantity": 1,
        "created": "2020-10-09T01:05:21Z",
        "transaction": {
            "id": "f6c8d531-a6f1-4df7-91a9-698265675fc0",
            "referenceId": "000901",
            "clientId": "urn:elli:client:DEBE11170913",
            "environment": "sandbox",
            "created": "2020-10-09T00:45:17Z",
            "updated": "2020-10-09T01:05:21Z",
            "entityRef": {
                "entityId": "urn:elli:encompass:DEBE11170913:loan:83138afd-3c04-400c-ab54-db8b03d6df34",
                "entityType": "urn:elli:encompass:loan"
            },
            "status": "completed",
            "request": {
                "type": "Life of Loan"
            },
            "response": {
                "referenceNumber": "000901"
            }
        },
        "product": {
            "id": "2984725b-6237-468a-ad18-fff368b2f6ec",
            "name": "Flood-DataVerifyCBC_204142861626554",
            "partnerId": "007001"
        }
    }
]

Did this page help you?