Reporting API - 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.
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:
- Get two sets of invoice headers and invoice rows for the same period – your incoming and your outgoing invoices (see previous section).
- If vendorInvoiceRowId value is returned than you can map incoming and outgoing invoices by using the following relations:
incoming.vendorInvoiceRowId = outgoing.vendorInvoiceRowId - If vendorInvoiceRowId is not returned, you can use the following relations:
- incoming.subscriptionId = outgoing.subscriptionId
- and incoming.chargeStartDate = outgoing.chargeStartDate
- and incoming.chargeEndDate = outgoing.chargeEndDate
- and incoming.chargeType = outgoing.chargeType
- and incoming.invoiceDate = outgoing.invoiceDate
- The incoming.TotalPrice from invoice rows then is your revenue and the outgoing.TotalPrice is your cost.
- 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.
|
Recon file column |
API endpoint |
Column |
|
Invoice number |
/invoices/invoice-headers |
invoiceNumber |
|
Invoice Status |
/invoices/invoice-headers |
invoiceStatus |
|
Invoice date |
/invoices/invoice-headers |
invoiceDate |
|
Invoice provider |
/invoices/invoice-headers |
providerName |
|
Invoice receiver |
/invoices/invoice-headers |
consumerName |
|
Receiver status |
/organizations or /organizations/details |
status |
|
Receiver ERP ID |
/organizations/details |
erpId |
|
Receiver country |
/organizations/addresses |
country |
|
Receiver VAT number |
/organizations/details |
vatNumber |
|
Contract number |
/contracts |
contractNumber |
|
Contract reference number |
/contracts |
contractReferenceNumber |
|
Reference contact person |
/organizations/contacts |
firstName + lastName |
|
Billing address |
/organizations/addresses |
|
|
Account manager |
/organizations/contacts |
firstName + lastName |
|
Account manager email |
/organizations/contacts |
firstName + lastName |
|
Comments |
n/a |
n/a |
|
Reseller name |
/organizations or /organizations/details |
fullName / shortName |
|
Customer name |
/organizations or /organizations/details |
fullName / shortName |
|
Offer name |
/invoices/invoice-rows |
offerName |
|
Subscription name |
/invoices/invoice-rows |
subscriptionName |
|
Subscription start date |
/subscriptions |
startDate |
|
Subscription end date |
/subscriptions |
endDate |
|
Charge start date |
/invoices/invoice-rows |
chargeStartDate |
|
Charge end date |
/invoices/invoice-rows |
chargeEndDate |
|
Charge type |
/invoices/invoice-rows |
chargeType |
|
Currency |
/invoices/invoice-rows |
currency |
|
Customer Unit price |
/invoices/invoice-rows (where invoice receiver = customer) |
unitPrice |
|
Customer quantity |
/invoices/invoice-rows (where invoice receiver = customer) |
quantity |
|
Customer total price |
/invoices/invoice-rows (where invoice receiver = customer) |
totalPrice |
|
Vendor |
/subscriptions |
vendorName |
|
Reseller Unit Price |
/invoices/invoice-rows (where invoice receiver = reseller) |
unitPrice |
|
Reseller Total Price |
/invoices/invoice-rows (where invoice receiver = reseller) |
quantity |
|
Reseller Currency |
/invoices/invoice-rows (where invoice receiver = reseller) |
totalPrice |
|
Support Currency |
n/a |
n/a |
|
Support Total Price |
n/a |
n/a |
|
Retail Price Source |
n/a |
n/a |
|
Retail Price Markup |
n/a |
n/a |
|
Customer Markup |
n/a |
n/a |
|
Price Markup Start Date |
n/a |
n/a |
|
Invoice Provider Id |
/invoices/invoice-headers |
providerOrganizationId |
|
Invoice Receiver Id |
/invoices/invoice-headers |
consumerOrganizationId |
|
Reseller Id |
/subscriptions |
resellerOrganizationId |
|
Customer Id |
/subscriptions |
customerOrganizationId |
|
Offer Id |
/subscriptions |
offerId |
|
Vendor Offer Id |
/offers |
offerExternalId |
|
Subscription Id |
/invoices/invoice-rows |
subscriptionId |
|
Vendor Subscription Id |
/subscriptions |
subscriptionExternalId |
|
Custom offer properties |
/offers/properties |
key + value |
|
Buyer Purchase Order Number |
n/a |
n/a |
|
Seller Purchase Order Number |
n/a |
n/a |
|
Invoice Reference # |
/invoices/invoice-headers |
invoiceReferenceNumber |
Was this article helpful?
Articles in this section
- Reporting API - Overview
- Reporting API - requesting access
- Reporting API - Data Model
- Reporting API - How to map your Invoice Data
- Reporting API - Detailed Invoice Line Items
- Reporting API - How to identify Organizations in your Sales Channel
- Reporting API - Currencies within the Invoices
- Reporting API : Preview invoices in status 'New'
- Reporting API - Using updatedDate Filters
- Reporting API - Viewing Vendor Invoice Row JSONs via API
Add comment
Please sign in to leave a comment.