Billing Data JSON #
The information below provides details of the JSON data provided when downloading the data for a specific invoice. The JSON data provides the most granular level of information, including entries for each user licence used and summary entries providing information on invoice totals and applicable taxes.
Invoice Details Schema #
The main JSON entry provides details about the invoice number, period and date. It also contains an array of the individual invoice items which relate to each licence being invoiced for.
| Key | Description | Type |
|---|---|---|
| tenantid | The id for the parent reseller account | string |
| invoiceid | A unique number to identify a particular invoice | string |
| invoicenumber | The invoice number displayed on the PDF invoice | string |
| accountname | The company name for the parent reseller account | string |
| billingperiodstart | The date the billing period starts | string |
| billingperiodend | The date the billing period ends | string |
| invoicevalue | The total value of the invoice | double |
| invoiceitems | A collection of invoice items | array(Invoice Item) |
JSON Invoice Item Schema #
Each invoice item entry in the JSON billing data provides the parameters listed below. They refer to an individual usage by a user with the applicable date ranges.
| Key | Description | Type |
|---|---|---|
| id | A unique id for the individual purchase | string |
| quantity1 | The quantity used | double |
| value | The cost of the item | double |
| fromdate | The date from which the item is being billed for | string |
| todate | The date from which the item is being billed to | string |
| calculationorder | Sequential number indicating the order in which the Invoice Items should be processed | int |
| operatorused | Indicates how the value of the Invoice Item is being applied to the invoice | Invoice Item Operator |
| operatorvalueused | Indicates the value of the ADJUSTPERCENTAGE operator | double |
| producttagname | The name of the feature/product the Invoice Item is for. This will be in the format '{PRODUCT_NAME} #{PART_NUMBER}' | string |
| billingoutputtags | Indication of whether the Invoice Item is for a purchase or is a summary field | array(string) |
| stringvalues | Provides information on the customer and end user the purchase is for | KeyValuePair<string,string> |
| numericvalues | Provides information on the customer and end user the purchase is for | KeyValuePair<string,double> |
Invoice Item Operators #
The operator for each item indicates how the item is being applied to the bill. PurchaseResult will have a PRICE to identify the cost of the item. Items with other output tags will indicate if they are summing up the value of the bill or applying a percentage value to previous items such as sales tax.
| Items | Description |
|---|---|
| PRICE | Indicates the Invoice Item is showing the unit price of an item |
| SUM | Indicates the Invoice Item is showing a total of multiple items |
| ADJUSTPERCENTAGE | Indicates the Invoice Item is showing a percentage adjustment to the SUM, this usually indicates VAT is being applied |
Billing Output Tag Items #
Billing output tags are used to indicate if the data entry relates to a purchase or is a summary entry providing information about the whole invoice.
| Items | Description |
|---|---|
| PurchaseResult | Indicates the Invoice Item is a chargeable purchase |
| Summary | Indicates the Invoice Item is a summary of purchases, providing information on the total of the invoice. When on its own without the 'TotalVAT' or 'TotalInclVAT' tags then it indicates the bill total before VAT is added. |
| TotalInclVAT | Indicates the Invoice Item is showing the invoice total including any applicable VAT |
| TotalVAT | Indicates the Invoice Item is showing the total applicable VAT for the invoice |
String Value Items #
The string value items provide information specific to the customer and end user of the purchased item.
| Key | Description | |
|---|---|---|
| TenantCode2 | The customer's tenant id | |
| TenantCodeext2 | The reseller's reference for the customer | |
| TenantName2 | The name of the customer | string |
| ResellerCode3 | The reseller tenant id | |
| ResellerCodeExt3 | The extended reference for the reseller | |
| ResellerName3 | The name of the reseller | |
| EndCustomerCode4 | The reseller tenant id (deprecated) | |
| EndCustomerCodeExt4 | The extended reference for the reseller (deprecated) | |
| EndCustomerName4 | The name of the reseller (deprecated) | |
| UserId | The id of the user | |
| Username | The username of the user | |
| customer_licence_count | The total number of these licences the customer has |
Example JSON Output #
{
"tenantId": "00000000-0000-0000-0000-123456789123",
"invoiceId": "00000000000000000000000a",
"invoiceNumber": "9000004",
"accountName": "Example Tenant 1",
"billingPeriodStart": "2020-04-01T00:00:00.0000000",
"billingPeriodEnd": "2020-04-30T23:59:59.0000000",
"invoiceDate": "2020-04-09T00:00:00.0000000",
"invoiceValue": 17.50,
"invoiceItems": \[
{
"id": "000000000000000000000001",
"quantity": 1.0,
"value": 1.25,
"fromDate": "2020-04-01T00:00:00.000+00:00",
"toDate": "2020-04-30T23:59:59.000+00:00",
"calculationOrder": 1,
"operatorUsed": "PRICE",
"operatorValueUsed": 1.25,
"productTagName": "Essential User #XDM00001",
"billingOutputTags": ["PurchaseResult"][ "PurchaseResult" ],
"stringValues": [
{
"name": "ResellerCode",
"value": "00000000-0000-0000-0000-000000000222"
},
{
"name": "ResellerCodeExt",
"value": "reseller ref 1"
},
{
"name": "ResellerName",
"value": "ABC Reseller"
},
{
"name": "TenantCode",
"value": "00000000-0000-0000-0000-000000000111"
},
{
"name": "TenantCodeExt",
"value": "custom ref 1"
},
{
"name": "TenantName",
"value": "Example Customer 1"
},
{
"name": "UserId",
"value": "00000000-0000-0000-0000-000000000001"
},
{
"name": "UserName",
"value": "[email protected]"
},
{
"name": "EndCustomerCode",
"value": "00000000-0000-0000-0000-000000000222"
},
{
"name": "EndCustomerCodeExt",
"value": "reseller ref 1"
},
{
"name": "EndCustomerName",
"value": "ABC Reseller"
}
][
{
"name": "ResellerCode",
"value": "00000000-0000-0000-0000-000000000222"
},
{
"name": "ResellerCodeExt",
"value": "reseller ref 1"
},
{
"name": "ResellerName",
"value": "ABC Reseller"
},
{
"name": "TenantCode",
"value": "00000000-0000-0000-0000-000000000111"
},
{
"name": "TenantCodeExt",
"value": "custom ref 1"
},
{
"name": "TenantName",
"value": "Example Customer 1"
},
{
"name": "UserId",
"value": "00000000-0000-0000-0000-000000000001"
},
{
"name": "UserName",
"value": "[email protected]"
},
{
"name": "EndCustomerCode",
"value": "00000000-0000-0000-0000-000000000222"
},
{
"name": "EndCustomerCodeExt",
"value": "reseller ref 1"
},
{
"name": "EndCustomerName",
"value": "ABC Reseller"
}
],
"numericValues": [
{
"name": "customer_licence_count",
"value": 1
}
][
{
"name": "customer_licence_count",
"value": 1
}
]
},
{
"id": "000000000000000000000003",
"quantity": 1.0,
"value": 15.0,
"fromDate": "2020-04-01T00:00:00.000+00:00",
"toDate": "2020-04-30T23:59:59.000+00:00",
"calculationOrder": 3,
"operatorUsed": "PRICE",
"operatorValueUsed": 15.00,
"productTagName": "Real-Time Supervisor #XDM00010",
"billingOutputTags": ["PurchaseResult"][ "PurchaseResult" ],
"stringValues": [
{
"name": "ResellerCode",
"value": "00000000-0000-0000-0000-000000000222"
},
{
"name": "ResellerCodeExt",
"value": "reseller ref 1"
},
{
"name": "ResellerName",
"value": "ABC Reseller"
},
{
"name": "TenantCode",
"value": "00000000-0000-0000-0000-000000000111"
},
{
"name": "TenantCodeExt",
"value": "custom ref 1"
},
{
"name": "TenantName",
"value": "Example Customer 1"
},
{
"name": "UserId",
"value": "00000000-0000-0000-0000-000000000001"
},
{
"name": "UserName",
"value": "[email protected]"
},
{
"name": "EndCustomerCode",
"value": "00000000-0000-0000-0000-000000000222"
},
{
"name": "EndCustomerCodeExt",
"value": "reseller ref 1"
},
{
"name": "EndCustomerName",
"value": "ABC Reseller"
}
][
{
"name": "ResellerCode",
"value": "00000000-0000-0000-0000-000000000222"
},
{
"name": "ResellerCodeExt",
"value": "reseller ref 1"
},
{
"name": "ResellerName",
"value": "ABC Reseller"
},
{
"name": "TenantCode",
"value": "00000000-0000-0000-0000-000000000111"
},
{
"name": "TenantCodeExt",
"value": "custom ref 1"
},
{
"name": "TenantName",
"value": "Example Customer 1"
},
{
"name": "UserId",
"value": "00000000-0000-0000-0000-000000000001"
},
{
"name": "UserName",
"value": "[email protected]"
},
{
"name": "EndCustomerCode",
"value": "00000000-0000-0000-0000-000000000222"
},
{
"name": "EndCustomerCodeExt",
"value": "reseller ref 1"
},
{
"name": "EndCustomerName",
"value": "ABC Reseller"
}
],
"numericValues": [
{
"name": "customer_licence_count",
"value": 1
}
][
{
"name": "customer_licence_count",
"value": 1
}
]
},
{
"id": "000000000000000000000004",
"quantity": 3.0,
"value": 17.50,
"fromDate": "2020-04-01T00:00:00.000+00:00",
"toDate": "2020-04-30T23:59:59.000+00:00",
"calculationOrder": 4,
"operatorUsed": "SUM",
"operatorValueUsed": 0.0,
"productTagName": "All Products",
"billingOutputTags": ["Summary", "Total", "GL", "GL_Entry:0000;credit;"][ "Summary", "Total", "GL", "GL_Entry:0000;credit;" ],
"stringValues": [][ ]
},
{
"id": "000000000000000000000005",
"quantity": 3.0,
"value": 17.50,
"fromDate": "2020-04-01T00:00:00.000+00:00",
"toDate": "2020-04-30T23:59:59.000+00:00",
"calculationOrder": 5,
"operatorUsed": "ADJUSTPERCENTAGE",
"operatorValueUsed": 0.0,
"productTagName": "All Products",
"billingOutputTags": ["TotalInclVAT", "Summary", "GL_Balance", "GL_Entry:2222;debit;Debtors"][ "TotalInclVAT", "Summary", "GL_Balance", "GL_Entry:2222;debit;Debtors" ],
"stringValues": [][ ]
},
{
"id": "000000000000000000000006",
"quantity": 345.0,
"value": 0.0,
"fromDate": "2020-04-01T00:00:00.000+00:00",
"toDate": "2020-04-30T23:59:59.000+00:00",
"calculationOrder": 6,
"operatorUsed": "ADJUSTPERCENTAGE",
"operatorValueUsed": 0.0,
"productTagName": "All Products",
"billingOutputTags": ["TotalVAT", "Summary", "GL_VAT", "VAT:S", "GL_Entry:1111;credit;VAT"][ "TotalVAT", "Summary", "GL_VAT", "VAT:S", "GL_Entry:1111;credit;VAT" ],
"stringValues": [][ ]
}
],
"invoiceType": 0
}-
If the invoice entry is a credit, the quantity will be a negative figure. ↩︎
-
The 'TenantCode', 'TenantCodeExt' and 'TenantName' fields are populated with information about the customer account the licence usage applies to. The 'TenantCodeExt' will be populated with the reseller's Reference number that has been configured against the reseller. ↩︎
-
The 'ResellerCode', 'ResellerCodeExt' and 'ResellerName' fields are populated with information about the reseller account the customer belongs to. The 'ResellerCodeExt' will be populated with the Reference number that has been configured against the reseller. This can be updated as required to allow linking of reseller records to external systems. ↩︎
-
These properties are deprecated and will be removed in a future release. ↩︎