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 license 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 license 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
quantity¹	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
TenantCode²	The customer's tenant id
TenantCodeext²	The reseller's reference for the customer
TenantName²	The name of the customer
ResellerCode³	The reseller tenant id
ResellerCodeExt³	The extended reference for the reseller
ResellerName³	The name of the reseller
EndCustomerCode⁴	The reseller tenant id (deprecated)
EndCustomerCodeExt⁴	The extended reference for the reseller (deprecated)
EndCustomerName⁴	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 licenses 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" ],
			"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"
				}
			],
			"numericValues": [
				{
					"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" ],
			"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"
				}
			],
			"numericValues": [
				{
					"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;" ],
			"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" ],
			"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" ],
			"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 license 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. ↩︎