Reporting API v1/v2 - invoice per order

Introduction

This article describes the Reporting API functionality that includes invoice frequency information for both v1 and v2 invoice headers endpoints. There are two fields to distinguish between invoices generated per billing cycle versus per order, providing better visibility into invoice generation patterns for API consumers.

In this article:

• Understanding Invoice Frequency Fields
• Version 1 API Extensions
• Version 2 API Extensions
• Field Population Logic
• API Response Examples
• Postman Collections

Understanding Invoice Frequency Fields

The endpoints include two fields that provide invoice frequency information:

• InvoiceFrequencyId: int, nullable - Used for internal logic/UI mapping (not displayed in UI)
• InvoiceFrequency: string, nullable - Maps to UI column "Invoice Frequency" with human-readable values

These fields help distinguish between:

• Per Billing Cycle: Invoices generated based on recurring billing cycles
• Per Order: Invoices generated for specific orders, connected to the feature: Invoice per Order.

Version 1 API Extensions

Affected Endpoints:

• GET /api/v1/reporting/invoices/invoice-headers/{requesterId}

• GET /api/v1/reporting/invoices/invoice-headers/{requesterId}/preview

Response Schema Changes:

Both endpoints include frequency fields in their response schema:

1.

GET /api/v1/reporting/invoices/invoice-headers/{requesterId}

GET /api/v1/reporting/invoices/invoice-headers/{requesterId}/preview

Version 2 API Extensions

Affected Endpoints:

• GET /api/v2/reporting/requesters/{requesterId}/invoices/headers

• GET /api/v2/reporting/requesters/{requesterId}/partners/{partnerId}/invoices/headers

Response Schema Changes:

Similar to v1, both v2 endpoints include frequency fields with the same structure and logic.

Field Population Logic

The system determines invoice frequency based on the presence of an OrderId in the invoice record:

When Invoices.OrderId is NULL:

• InvoiceFrequency = "Per Billing Cycle"
• InvoiceFrequencyId = 0 (from InvoiceFrequencyTypes where Name = "Per Billing Cycle")

When Invoices.OrderId is not NULL:

• InvoiceFrequency = "Per Order"
• InvoiceFrequencyId = 1 (from InvoiceFrequencyTypes where Name = "Per Order")

API Response Examples

Response example for InvoiceFrequencyId = 1:

Postman Collections

Summary

The Reporting API provides comprehensive invoice frequency information across both v1 and v2 invoice headers endpoints. This enables better categorization and reporting of invoice generation patterns while maintaining full backward compatibility with pre-existing API consumers. These fields distinguish between invoices generated per billing cycle versus per order, providing valuable insights into invoice generation workflows.

Related Content

• Reporting API - Overview
• Reporting API - Requesting Access
• Invoice per order