Reporting API - How to identify Organizations in your Sales Channel

Introduction

Identifying organizations in your sales channel gives context to other data, such as invoices and subscriptions, as well as lets you build a list of all of your customers, whether they are transacting or not.

Knowing your full sales channel will allow you to generate insights, such as:

• Number of customers with and without subscriptions
• Customer churn
• Seller churn (if applicable)
• Seller Cost, Revenue and Margin
• Distributor Cost, Revenue and Margin (if applicable)

To manage this organization hierarchy, the platform uses Contracts joined in parent-child relationships. This data is available in the Reporting API Contracts endpoint where the contractPurpose is either Resell or Consume.

This hierarchy relates to the Subscriptions endpoint data where Subscriptions.vendorContractId = Contracts.contractId.

“Resell” and “Consume” purpose contracts

The purpose of the resell and consume contracts is to describe the hierarchy of organizations that can sell to one another.

This hierarchy is built based on parent/child relationships between contracts using contractId and parentContractId values.

Note – depending on your role in the hierarchy, you may not have access to the complete hierarchy. However, you should still be able to identify the organizations that are relevant to your organization’s role.

Related article: Invoicing by contract

Consume contracts: contractPurposeId = 1, contractPurpose = Consume. These contracts are created between the Vendor (as the contractProvider) and the End Customer (as the contractConsumer). This means that the End Customer can, technically, purchase offers from this Vendor.

Resell contracts: contractPurposeId = 0, contractPurpose = Resell. These contracts are set between all non-customer participants. They build the hierarchy of which organizations can, technically, sell to which.

Contract hierarchy examples

Here are the most common examples of contract hierarchies, with Provider and Consumer organization roles defined.

1-tier hierarchy

2-tier hierarchy

Multi-tier hierarchy