Monthly platform finance schema

What the monthly platform finance schema is for

The monthly platform finance schema is the Netice field contract for platform finance reporting. It is the schema used by the finance_unified source mode. The schema is intended for Apple App Store Connect financeReports and Google Play monthly Earnings reports, normalized into a source-aware monthly finance output.

The output is event-grain. That means it should not be read as “one row per app per month.” A row represents an economic event or finance report line after Netice has preserved the platform source, report family, period, event type, native currency, report currency and lineage context. Apple and Google Play do not expose identical finance reports, so the schema keeps their differences visible instead of flattening everything into a generic revenue number.

This schema applies across customer-owned destinations such as BigQuery, Snowflake, Google Cloud Storage and AWS S3. The destination changes the delivery format, not the meaning of the fields. The semantic contract remains finance_unified.

Source reports and source kind

The core identifier for this layer is source_kind = 'FINANCE'. This separates finance rows from daily sales rows before they ever reach a dashboard, warehouse model or AI-generated summary.

This distinction matters because daily app-sales tables and monthly finance tables can both contain revenue-related numbers, but they answer different questions. Finance rows are period-aware, event-aware and source-report-aware. They should not be written into daily app-sales artifacts or interpreted through daily app-sales fields such as revenue_date, estimated_net or data_completeness.

Canonical field groups

The finance schema has a stable field order that acts as the cross-destination contract. BigQuery tables, Snowflake tables, CSV bundles, schema JSON and tests all rely on the same field sequence. The field list is intentionally richer than a simple revenue table because platform finance data needs period, event, currency, finality and lineage context.

Field-level reference

The table below gives the practical interpretation of the most important fields. It is not a full database dump; it is the field contract a finance or data team needs before using the output in a warehouse, storage bucket or downstream BI model.

Apple financeReports behavior

Apple finance rows in this schema come from App Store Connect financeReports, not Sales and Trends reports. That distinction is not cosmetic. Apple Summary Sales and Apple financeReports have different purposes, fields, periods and finance meaning.

Apple finance rows preserve Apple fiscal-period context. Fields such as fiscal_period, apple_fiscal_label, period_start, period_end and period_calendar_type help downstream teams avoid treating Apple fiscal periods as ordinary calendar months.

Apple finance behavior is also asymmetric with Google. Apple finance output emits sale and refund finance events where those are supported by the source. It does not fabricate separate platform fee or tax events when Apple does not disclose them as separate source facts. That is why fields such as commission_disclosed and null handling matter.

Google Play Earnings behavior

Google Play finance rows in this schema come from Google Play monthly Earnings reports, not Google Play Estimated Sales. Earnings reports are monthly finance-style reports and can preserve ledger-like event rows.

Google finance output can include event types such as SALE, REFUND, PLATFORM_FEE, PLATFORM_FEE_REVERSAL, TAX and ADJUSTMENT. Fee and tax rows can have null customer-charge fields because they are not customer charge events. This is expected and should not be interpreted as missing sales data.

Google Play Earnings should not be described as including chargebacks unless that is separately supported. The finance schema should preserve what the provider reports, not invent unsupported event categories.

Monthly, fiscal-period and calendar-period semantics

Finance output is period-based. It is not a daily date table. The schema uses fiscal_period for platform-native statement periods and calendar_period as a calendar bucket. Apple and Google are not identical here.

Apple Finance Reports use fiscal periods. Apple rows can preserve period_start, period_end, fiscal_period and apple_fiscal_label. Google Play Earnings reports are monthly, and Google fiscal period and calendar period are usually the same month start in the current mapping.

The finance replacement scope is based on finance period and source scope. It is not the same as refreshing daily app-sales windows by revenue_date. This prevents monthly finance output from being accidentally treated like a daily sales table.

Native currency, report currency and FX

Native values remain native in the finance schema. Fields such as native_currency, native_net_proceeds and native_customer_charge preserve the provider-side amount context. Report-currency fields such as report_currency, report_net_proceeds, report_customer_charge and fx_rate are presentation fields.

Same-currency conversion can use an FX rate of 1. Cross-currency conversion must have a resolvable FX rate. If the rate is missing, report-currency fields remain null rather than silently becoming fake values.

Apple and Google differ here as well. Apple native proceeds come from Apple finance report proceeds context. Google native proceeds come from Google Earnings merchant-currency amounts. Google fee, tax and adjustment rows may not have a customer charge. Apple finance does not reconstruct exact separate Apple fee/tax rows from the spread.

Null-not-zero policy

The finance schema intentionally treats unknown values differently from zero. Unknown finance amounts remain null. Real zero remains zero. That distinction is important because a fake zero can look like a real finance fact and flow into close, reconciliation or BI logic.

Source lineage and safe metadata

Finance output needs traceability, but public documentation and safe summaries must not expose raw provider rows, real vendor numbers, app IDs, SKUs, object paths, source files, credentials, logs, task IDs or customer data.

The schema includes lineage fields such as source_file_name, source_file_uri, source_row_number, source_row_hash, source_vendor_hash, source_schema_version and raw_metadata. In public examples, these should always be synthetic. In product behavior, these fields support provenance and diagnostics without turning the schema into a raw source dump.

Finality and period status

The is_final field is a derived finance finality field. It is false at ingest and later derived from period status after successful materialization and source-data stability. It should not be described as a provider-guaranteed audit flag or accounting close approval.

Current evidence describes a default finality policy based on business days after period end and after the latest source data change. That is an operational finality policy for the finance output. It does not replace the customer’s accounting process.

Destination output: BigQuery, Snowflake, GCS and S3

The same finance schema applies across supported destinations. Warehouse destinations provide managed tables. Object-storage destinations provide a finance CSV and related sidecar artifacts.

Finance destinations should not collide with daily app-sales artifact names. A finance output should not write into daily sales tables or files, and a daily sales output should not write into finance artifacts.

Format changes and schema drift

Apple and Google can add or change source report columns. The finance schema is designed around source-specific parsers and header-based parsing rather than fragile column-position assumptions. New optional columns can be handled as metadata. Missing required headers should produce a clear failure rather than silently changing the meaning of finance rows.

Schema-drift warnings should expose bounded schema metadata, not raw row values. A provider format change is a support and data-quality condition. It is not the same thing as zero revenue.

Safe synthetic examples

The examples below are synthetic and shortened for readability. They show the shape of the finance schema without using real app IDs, SKUs, vendor numbers, source files, hashes, destinations, credentials, task IDs, logs or customer amounts.

Apple finance sale row

platform,source,source_kind,source_report,report_grain,fiscal_period,apple_fiscal_label,period_calendar_type,event_type,event_category,commission_disclosed,native_currency,native_net_proceeds,native_customer_charge,report_currency,report_net_proceeds,report_customer_charge,fx_rate,is_final,source_row_hash
IOS,APPLE_APP_STORE,FINANCE,APPLE_FINANCE_DETAIL,APPLE_FINANCE_DETAIL,2026-04-01,FY26-M04,APPLE_FISCAL_MONTH,SALE,REVENUE,false,EUR,6.990000,9.990000,EUR,6.990000,9.990000,1,false,synthetic_hash_apple_finance_001

Google Play finance ledger rows

platform,source,source_kind,source_report,report_grain,fiscal_period,period_calendar_type,event_type,event_category,event_subtype,commission_disclosed,native_currency,native_net_proceeds,native_customer_charge,report_currency,report_net_proceeds,report_customer_charge,fx_rate,is_final,source_row_hash
ANDROID,GOOGLE_PLAY,FINANCE,GOOGLE_PLAY_EARNINGS,GOOGLE_EARNINGS_LEDGER_LINE,2026-04-01,GOOGLE_PLAY_EARNINGS_MONTH,SALE,REVENUE,,true,EUR,9.990000,9.990000,EUR,9.990000,9.990000,1,false,synthetic_hash_google_charge_001
ANDROID,GOOGLE_PLAY,FINANCE,GOOGLE_PLAY_EARNINGS,GOOGLE_EARNINGS_LEDGER_LINE,2026-04-01,GOOGLE_PLAY_EARNINGS_MONTH,PLATFORM_FEE,DEDUCTION,COMMISSION,true,EUR,-3.000000,,EUR,-3.000000,,1,false,synthetic_hash_google_fee_001

In the Google fee row, the customer-charge fields are blank intentionally. That blank means null, not zero. A platform fee ledger row is not a customer charge row.

Monthly finance query

SELECT
  platform,
  fiscal_period,
  source_report,
  SUM(report_net_proceeds) AS report_net_proceeds
FROM `example_project.example_dataset.finance_unified`
WHERE fiscal_period = DATE '2026-04-01'
  AND source_kind = 'FINANCE'
GROUP BY platform, fiscal_period, source_report
ORDER BY platform, source_report;

Event mix query

SELECT
  platform,
  source_report,
  event_type,
  event_category,
  SUM(report_net_proceeds) AS report_net_proceeds
FROM `example_project.example_dataset.finance_unified`
WHERE fiscal_period = DATE '2026-04-01'
GROUP BY platform, source_report, event_type, event_category
ORDER BY platform, event_type;

These queries are examples for monthly platform finance output. They are not accounting close instructions and not bank reconciliation guarantees.