Reporting API v1 - 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.

In this article:

• “Resell” and “Consume” purpose contracts
• Contract hierarchy examples

“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

Summary

Organizations in your sales channel are identified through Contracts joined in parent-child relationships, available in the Reporting API Contracts endpoint where contractPurpose is either "Resell" or "Consume". This hierarchy allows you to generate insights such as customer and Seller churn, subscription counts, and Cost, Revenue, and Margin data for Sellers and Distributors. Consume Contracts (contractPurposeId = 1) are created between vendors and End Customers, while Resell Contracts (contractPurposeId = 0) are set between all non-customer participants to build the sales hierarchy. The Contract hierarchy relates to Subscriptions through the vendorContractId field, and depending on your role, you may only have access to the portion of the hierarchy relevant to your Organization.