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 Workflow
-
Create the billing rule
An EPC integration developer can create a billing rule record by calling thePOSTAPI(/v2/products/:id)and pass the billing information. The POST will always create a record in DRAFT status. -
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
-
Contact your IMT Relationship Manager/Solutions Architect to initiate a review of your submission
-
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"
}
}
]
Updated almost 3 years ago