Reporting API v1 - how to map your invoice data

Introduction

The invoice-headers and invoice-rows endpoints return the data for all invoices relevant to your organization.

If you are a customer, then these will only be your incoming invoices.

If you are a reseller, then these will be your incoming and outgoing invoices.

If you are a multi-tier reseller or a distributor, then these will be your incoming and outgoing invoices, as well as the incoming and outgoing invoices of organizations in your sales channel.

Each invoice has two IDs associated – providerOrganizationId – the organization sending the invoice and consumerOrganizationId – the organization receiving the invoice.

In this article:

• Identifying incoming & outgoing invoices
• Finding your cost and revenue for each subscription
• Mapping invoices to the reconciliation file

Identifying incoming & outgoing invoices

Your incoming invoices are those where the consumerOrganizationId is your organization ID. Your outgoing invoices are those where the providerOrganizationId is your organization ID.

In most cases your organization ID will be the same as the requesterId used to access all Reporting APIs.

Finding your cost and revenue for each subscription

By identifying your incoming & outgoing invoices you may also find your cost and revenue for each subscription, which also lets you calculate your margin.

To do so you need to complete the following:

1. Get two sets of invoice headers and invoice rows for the same period – your incoming and your outgoing invoices (see previous section).
2. If vendorInvoiceRowId value is returned than you can map incoming and outgoing invoices by using the following relations:
   incoming.vendorInvoiceRowId = outgoing.vendorInvoiceRowId
3. If vendorInvoiceRowId is not returned, you can use the following relations: 
   1. incoming.subscriptionId = outgoing.subscriptionId
   2. and incoming.chargeStartDate = outgoing.chargeStartDate
   3. and incoming.chargeEndDate = outgoing.chargeEndDate
   4. and incoming.chargeType = outgoing.chargeType
   5. and incoming.invoiceDate = outgoing.invoiceDate
4. The incoming.TotalPrice from invoice rows then is your revenue and the outgoing.TotalPrice is your cost.
5. Note that you should make sure that the currency is the same for incoming and outgoing invoices. If it is not, you need to apply a currency exchange rate if you want to your margin or other metrics.

Mapping invoices to the reconciliation file

Many of the key values from the invoice recon file can be mapped to the Reporting API. Please see the mapping below.

Summary

The invoice-headers and invoice-rows endpoints return Invoice data relevant to your Organization, with incoming Invoices where consumerOrganizationId matches your Organization ID and outgoing Invoices where providerOrganizationId matches your Organization ID. To find Cost and Revenue for each Subscription, retrieve both incoming and outgoing Invoices for the same period and map them using vendorInvoiceRowId if available, or by matching subscriptionId, chargeStartDate, chargeEndDate, chargeType, and invoiceDate. The incoming totalPrice represents your Revenue while the outgoing totalPrice represents your Cost, allowing you to calculate margins when currencies match or after applying exchange rates. Many key values from the Invoice reconciliation file can be mapped to the Reporting API for data integration.