Warning: Orion’s billing platform is both powerful and complex. Any customer or partner seeking to connect to it through the API should first become well acquainted with its best practices, processes, and functionality. This should even include processing several months or even quarters worth of fees to fully understand the nuances and create a clear vision of custom functionality within the guardrails already put in place which have been tested and matured by years of customer use. Please consider reviewing your use case and process with a Billing product specialist before beginning on your solution.
Purpose: To find a Household or Account’s bill market value and fee amount, a bill instance must be created and then processed to calculate these values for the particular entity. Orion’s billing platform is the most flexible and advanced billing engine available and therefore it is always best to let the platform calculate all billing aspects rather than try and replicate the various rules, calculations, and cross-dependencies. This guide provides steps for creating, processing, reviewing, and deleting a bill instance within the Orion platform. All options available for creating a bill instance within the Orion Connect UI are available through the API.
Simple Use Case: Firm wants to calculate fees at a points during the quarter to regularly forecast the fees due to their Advisors. They will generate these Bill instances, gather the data needed, and then delete the Bill instance so that it does not interfere with normal billing processes.
Scope and Outputs: This API process can be used to generate a standard or mock/forecast bill instances.
Reference values listed below for initial instance Creation:
- Bill type
- Renewal =1
- New Money=2
- Performance =5
- Financial Planning =4
- Run For
- All Households = 0
- Fund Family =1
- Custodian =2
- Representative =3
- Business Line = 4
- Single Household – New Bill = 5
- Account(s) = 7
- Import bills from list = 8
- Override Bill End Date (Include date)
- Override As Of Value Date (Include date)
- Override Recurring Adjustment :true
- Include chosen values in the Key section (Fund Family ID, Custodian ID, Rep ID, Business Line ID, client ID Account ID)
Process Overview:
- Create a Bill Instance
- Generate Bills
- Request and Review Data
- Optional – Generate and Download Audit Files
- Optional – Generate and Download Fee Files
See Tips section for how to Delete a Bill Instance – this is optional but only available for forecast/mock instances.
Process Steps:
- Create a bill instance by passing a payload of values and parameters that make up the attributes of the instance. Update the asOfDate for date the instance should be run for. For a forecast/mock bill set “isMockBill”:true.
POST https://api.orionadvisor.com/api/v1/Billing/BillGenerator/Action/Instance
{
"nickName":"Bill Instance API",
"dateRange":null,
"runFor":0,
"Keys":[],
"asOfDate":"09/30/2021",
"billType":1,
"vHint":5,
"pkKey":null,
"endDateOverride":null,
"recurringAdjustmentOverride":false,
"acctList":null,
"valueAsOfOverride":null,
"isMockBill":false,
"IncludeCashFlow":1,
"runForAccounts":1
}- Call the Instance Details. This provides the basic details for the Bill Instance which would allow the user to review key attributes such as the status of the bill instance, the period start and end date, and whether or not this instance is for a mock run for forecast billing.
GET https://api.orionadvisor.com/api/v1/Billing/Instances/221
{
"id": 221,
"nickName": "API Test 1",
"statusValue": "Not Generated",
"runForGroup": "All Households",
"runForAccounts": "Active Accounts",
"billType": "Renewal",
"isMockBill": true,
"periodStart": null,
"periodEnd": null,
"householdCount": 121,
"marketValue": 0.0000,
"balanceDue": 0.00,
"createdDate": "2021-10-18",
"createdBy": "Jeff.Kliewer",
"hasValidBills": false,
"allowDuplicateMockBills": false,
"endDateOverride": null,
"asOfDate": "2021-09-30T00:00:00-05:00",
"valueDateOverride": null
}- Generate Bills. This action will put the database in billing lockdown so that no changes will be allowed to any client, account, or fee schedule which might interfere with accurate billing calculation. Then this step calculates the fees for the instance, updating that data in the instance record.
PUThttps://api.orionadvisor.com/api/v1/Billing/Instances/{Key}/Action/Generate?lockdown=true
- With the calculations complete, call for the details of the bill instance to retrieve the fully generated fee data. This will provide the calculated details for each entity included in the bill instance.
GEThttps://api.orionadvisor.com/api/v1/Billing/BillGenerator/Instance/221/ClientList?$top=10000
[{
"id": 873,
"billInstanceId": 221,
"billType": "Renewal",
"clientId": 49,
"clientName": "Franklin, Benjamin And Deborah",
"status": "Not Generated",
"startDate": "2021-10-01",
"endDate": "2021-12-31",
"initialAmt": 123.00,
"adjAmt": 156.00,
"balanceDue": 5.00,
"marketValue": null,
"feeAmount": null,
"feeFileGenerated": false,
"createdBy": "Jeff.Kliewer",
"createdDate": "2021-10-18T20:14:18.36-05:00",
"updatedBy": null,
"billId": null,
"errorMessage": null,
"repName": "OCTestRep2 OCTestRep2",
"repID": 92,
"relatedHouseholds": ""
}]- Optional – Create Audit Files – NOTE: In all cases of working with live bills it is critical that a firm follows Orion’s best practices for auditing and reviewing bills prior to submitting the files to the custodians. As such, this step is only optional, if you don’t plan to move forward in generating the fee files. If you do plan to generate fee files through the API, we recommend doing this step via the UI/UX within Orion Connect, but the output reports can be generated through the API, and must be completed before fee files can be created.
POSThttps://api.orionadvisor.com/api/v1/Billing/Instances/{key}/Action/BillDataFiles
- Optional (see note above) – Retrieve Audit File Information. This step will retrieve the records within the audit reports which should be reviewed and addressed before generating the fee files.
GET https://api.orionadvisor.com/api/v1/Billing/AuditFiles?BillInstanceId={key}
[{
"createdDate": "2021-10-22T15:09:11.533-05:00",
"id": 22298,
"openWith": "application/excel",
"fileName": "payable summary data.XLSX",
"blobDesc": "Payable Summary",
"blobText": null,
"category": null,
"isZip": false
}, {
"createdDate": "2021-10-22T15:09:09.407-05:00",
"id": 22297,
"openWith": "application/excel",
"fileName": "reconciliation data.XLSX",
"blobDesc": "Reconciliation Data",
"blobText": null,
"category": null,
"isZip": false
}, {
"createdDate": "2021-10-22T15:09:09-05:00",
"id": 22296,
"openWith": "application/excel",
"fileName": "billing data.XLSX",
"blobDesc": "Billing Data",
"blobText": null,
"category": null,
"isZip": false
}, {
"createdDate": "2021-10-22T14:51:53.11-05:00",
"id": 22295,
"openWith": "application/excel",
"fileName": "billing audit.CSV",
"blobDesc": "Billing Audit",
"blobText": null,
"category": null,
"isZip": false
}]- Optional (see note above) – Download Audit Files. This step is an alternative method to step 6 of reviewing the audit data which will return an exported file of the audit reports.
GET https://api.orionadvisor.com/api/v1/Billing/Audit/{key}/File?Authorization={authkey}
- Optional – Generate Fee Files. This step will generate the necessary fee files which can be submitted to the custodians for processing of the necessary fee transactions. This step is only needed if you intend to download and submit the fee files directly to the Custodian. Orion does have direct integrations to some of the custodians to submit the files directly to the custodian from Orion Connect. These cannot be activated from the API.
POST https://api.orionadvisor.com/api/v1/Billing/Instances/Action/FeeFiles
[key]- Optional – Retrieve Fee File Information. This call will retrieve a list of the available fee files for the given date range.
GET https://api.orionadvisor.com/v1/Trading/TradeFiles/Fees?startDate=2021-09-25&endDate=2021-10-23
[{
"id": 827,
"tradeFormat": "Fee List by Fund",
"createdBy": "Lori.Beaune",
"createdDate": "2021-10-22T16:46:33.187-05:00",
"fileName": "Bonds_FeeList_102221.csv",
"transmitMethod": "Network",
"status": "Not Sent",
"processBy": "Lori.Beaune",
"processDate": null,
"uploadTargetId": 8,
"instanceId": null
},]
- Optional – Using this call, you can download available Fee Files using the given file ID.
GET https://api.orionadvisor.com/v1/Trading/TradeFiles/{key}/File?Authorization={key}
Process Tips or Controls:
- When using this solution, it is helpful to become familiar with all of Orion’s billing best practices and even to have successfully generated bills through the Orion platform several times before looking to calculate and pull instance data through the API.
- To run a Forecast Bill instance IsMockBill will be “true” in the initial instance creation payload.
- For those using this solution to create mock data for forecasting, it may be valuable to delete the mock instances after data has been retrieved so as to not clutter up your Instance list.
Optional – Delete the Instance. Do NOT do this step if you have generated fees and processed those fees with the Custodian. You will have no records to review back in Orion should you need to audit the data in the future. This step will completely delete the Bill Instance record from Orion. Keep in mind this step will NOT delete any fee transactions or fee files created.
PUT https://api.orionadvisor.com/api/v1/Billing/Instances/Action/Delete/
[key] – You need the brackets