Reporting API v1 - how to map your invoice data

Appxite Updated by Appxite

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

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 matching your incoming and outgoing invoices, you can calculate the cost and revenue for each subscription – and from there, your margin.

To do this:

1. Pull your invoice data

Get invoice headers and invoice rows for the same period, for both your incoming and outgoing invoices (see the previous section).

2. Match the invoices

Preferred method: If vendorInvoiceRowId is returned, use it to match records directly:

incoming.vendorInvoiceRowId = outgoing.vendorInvoiceRowId

Fallback method: If vendorInvoiceRowId is not returned, match records using all of the following fields together:

  • subscriptionId
  • chargeStartDate
  • chargeEndDate
  • chargeType
  • quantity
  • meterId
  • offerId
  • invoiceDate
  • invoiceHeader.invoiceSource

(i.e. incoming.subscriptionId = outgoing.subscriptionId, incoming.chargeStartDate = outgoing.chargeStartDate, and so on for each field above.)

NOTE! If you’re using includeOtherSources=true when requesting invoice-rows and invoice-headers, always include invoiceSource in the match – even when vendorInvoiceRowId is available – to make sure only correctly matched source lines are mapped. 

3. Calculate revenue and cost

  • incoming.TotalPrice = your revenue
  • outgoing.TotalPrice = your cost

4. Check your currencies

Make sure incoming and outgoing invoices use the same currency. If they don’t, apply a currency exchange rate before calculating margin or other metrics.

NOTE! Records from ~/invoice-headers with invoiceSource = Platform are platform-generated invoices – these are the same invoices you see in the Platform UI under Billing. 

About invoiceSource = VendorApi

Records with invoiceSource = VendorApi (and their related invoice-rows) represent raw vendor invoice lines. These are reference data only – the original vendor charges mapped into the AppXite platform structure – and this method is now considered legacy.

For retrieving raw vendor invoice lines, we recommend using this API instead:

Reporting API v1 – viewing vendor invoice row JSONs via API 

With this endpoint, vendorInvoiceRowId matches directly to the vendorInvoiceRowId returned by the Reporting API invoice-rows endpoint, giving you accurate mapping between Reporting API invoice rows and the corresponding raw vendor incoming invoice lines.

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

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, quantity, meterId, offerId, invoiceDate, and invoiceSource.

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.

Note that vendorInvoiceRowId may correctly be NULL in certain expected cases (e.g., invoiceSource = VendorApi, chargeType = UsageFee, or rows generated via Billing Logic rather than Invoice Parsing). This does not indicate a data error.

For retrieving raw vendor invoice lines, use the dedicated "Reporting API v1 - viewing vendor invoice row JSONs via API" endpoint instead.

Many key values from the Invoice reconciliation file can be mapped to the Reporting API for data integration.

 

 

Related to

Reporting API

Was this article helpful?

1 out of 1 found this helpful

Articles in this section

Add comment

Please sign in to leave a comment.